MCP authentication

Choose an authentication method

Authenticate MCP requests with either a NomadFiling API key or an OAuth 2.1 access token. Use API keys for server-to-server access you control directly, and use OAuth when you are building a client that signs users in and needs delegated access.

Authorization: Bearer nf_example_9xmk7q2r4b7m8n2p6t1v5c8a

Authorization: Bearer mcp_at_example_7jd3p4n8q2r6s1t5v9w0x3y6

Send authenticated requests

Pass the credential in the Authorization header as a bearer token. The MCP server accepts the same header pattern for both authentication methods.

curl https://mcp.nomadfiling.com/tools/call \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer nf_example_9xmk7q2r4b7m8n2p6t1v5c8a" \
  -d '{
    "jsonrpc": "2.0",
    "id": "req_7aK2mP",
    "method": "tools/call",
    "params": {
      "name": "get_filing_status",
      "arguments": {
        "filingId": "fil_9m2x8q1p"
      }
    }
  }'

const response = await fetch("https://mcp.nomadfiling.com/tools/call", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer nf_example_9xmk7q2r4b7m8n2p6t1v5c8a"
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: "req_7aK2mP",
    method: "tools/call",
    params: {
      name: "get_filing_status",
      arguments: {
        filingId: "fil_9m2x8q1p"
      }
    }
  })
});

const data = await response.json();
console.log(data);

import requests

response = requests.post(
    "https://mcp.nomadfiling.com/tools/call",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer nf_example_9xmk7q2r4b7m8n2p6t1v5c8a",
    },
    json={
        "jsonrpc": "2.0",
        "id": "req_7aK2mP",
        "method": "tools/call",
        "params": {
            "name": "get_filing_status",
            "arguments": {
                "filingId": "fil_9m2x8q1p"
            }
        },
    },
)

print(response.json())

If authentication succeeds, the request continues to the selected tool with the authenticated user_id in context. If authentication fails and the method is tools/call, the server returns an authentication challenge.

Use a NomadFiling API key

API keys are the simplest option for backend services, scripts, and private automations. Each key is created once in the NomadFiling app and only its hash is stored on the server.

Create an API key

Generate API keys from the NomadFiling app at /account/api-keys. Enter a name for the key, generate it, then copy the plaintext value before closing the dialog.

A valid API key has the format nf_ followed by 64 hexadecimal characters. The full string is 67 characters long, including the prefix.

nf_example_9xmk7q2r4b7m8n2p6t1v5c8a

API key format and validation

API key authentication result

When validation fails, the API key authenticator returns null. For tools/call, the request then fails with the 401 Unauthorized response shown earlier.

Use OAuth 2.1 with PKCE

OAuth 2.1 adds client registration, user consent, short-lived access tokens, and rotating refresh tokens. NomadFiling supports the authorization code grant and refresh token grant.

OAuth endpoints

Complete OAuth flow

https://mcp.nomadfiling.com/authorize?client_id=mcp_client_example_1234567890abcdef&redirect_uri=https%3A%2F%2Fstudio.acme.dev%2Foauth%2Fcallback&response_type=code&state=example_state_value&code_challenge=example_code_challenge_value&code_challenge_method=S256&scope=mcp

curl -i "https://mcp.nomadfiling.com/authorize?client_id=mcp_client_example_1234567890abcdef&redirect_uri=https%3A%2F%2Fstudio.acme.dev%2Foauth%2Fcallback&response_type=code&state=example_state_value&code_challenge=example_code_challenge_value&code_challenge_method=S256&scope=mcp"

Dynamic client registration reference

Use /register to create a client before starting the OAuth flow.

Request body

Response fields

Authorization endpoint reference

Use /authorize to validate the client request and forward the user into the NomadFiling consent flow.

Query parameters

Behavior

If the request is valid, the server returns 302 Found and redirects the browser to https://app.nomadfiling.com/oauth/authorize with the request parameters forwarded. After the user approves access, the app calls /approve, generates an authorization code, and redirects the browser to your redirect_uri with code and state.

Token endpoint reference

Use /token for both authorization code exchange and refresh token rotation.

Authorization code grant

Refresh token grant

Token response fields

Token endpoint errors

Token formats and lifetimes

Each credential type has a fixed prefix and storage pattern. The server hashes secrets before lookup except for client IDs and authorization codes.

All tokens are generated with crypto.getRandomValues and base64url encoding, except API keys, which are shown as hexadecimal after the nf_ prefix. Refresh token rotation is enforced, so each successful refresh revokes the previous token row and issues a new token pair.

Security notes

FAQ

Related pages