MCP server overview

Connect AI agents to Nomadfiling through the Model Context Protocol server — learn about the protocol, transport, authentication, and available endpoints.

curl -X POST "{API_BASE_URL}/mcp-server" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "init_001",
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "clientInfo": {
        "name": "acme-agent",
        "version": "1.0.0"
      }
    }
  }'

const response = await fetch("{API_BASE_URL}/mcp-server", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: "init_001",
    method: "initialize",
    params: {
      protocolVersion: "2025-06-18",
      clientInfo: {
        name: "acme-agent",
        version: "1.0.0"
      }
    }
  })
})

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

{
  "jsonrpc": "2.0",
  "id": "init_001",
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "serverInfo": {
      "name": "nomadfiling-mcp",
      "version": "1.1.0"
    },
    "instructions": "NomadFiling MCP — manage US LLC filings (Form 5472/1120, Partnership, K-1, 8804/8805). Use get_form_schema first, then create_filing."
  }
}

curl -X POST "{API_BASE_URL}/mcp-server" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer nf_example_9xmk7q2r4b7m8n2p6t1v5c8a" \
  -d '{
    "jsonrpc": "2.0",
    "id": "tool_001",
    "method": "tools/call",
    "params": {
      "name": "get_form_schema",
      "arguments": {
        "formType": "form-5472-1120"
      }
    }
  }'

const response = await fetch("{API_BASE_URL}/mcp-server", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer nf_example_9xmk7q2r4b7m8n2p6t1v5c8a"
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: "tool_001",
    method: "tools/call",
    params: {
      name: "get_form_schema",
      arguments: {
        formType: "form-5472-1120"
      }
    }
  })
})

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

{
  "jsonrpc": "2.0",
  "id": "tool_001",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{"formType":"form-5472-1120","schema":{"type":"object"}}"
      }
    ],
    "structuredContent": {
      "formType": "form-5472-1120",
      "schema": {
        "type": "object"
      }
    }
  }
}

Connect agents to the Nomadfiling MCP server

Nomadfiling exposes a Model Context Protocol server for AI agents that need to discover filing tools, read tool schemas, and create filings over a standard JSON-RPC interface. The server uses streamable HTTP transport and stays stateless between requests.

Authenticate only tools/call requests. Methods such as initialize, ping, and tools/list work without authentication, which lets clients discover capabilities before presenting a login or API key flow.

Server identity

Use these values when configuring MCP clients or validating the initialize response.

baseUrlstring

Required

{API_BASE_URL}/mcp-server

runtimestring

Serverless runtime.

transportstring

Streamable HTTP.

sessionModelstring

Stateless. The server does not rely on persistent sessions between requests.

protocolVersionstring

2025-06-18

serverNamestring

nomadfiling-mcp

serverVersionstring

1.1.0

appUrlstring

https://app.nomadfiling.com

instructionsstring

NomadFiling MCP — manage US LLC filings (Form 5472/1120, Partnership, K-1, 8804/8805). Use get_form_schema first, then create_filing.

What the server is for

The MCP server is designed for agent-driven filing workflows. A client typically connects, reads the available tools, requests the schema for a form, and then submits structured filing data.

That makes the server a good fit for:

AI desktop clients such as Claude Desktop
Chat-based integrations that support MCP connections
Custom agent runtimes that can send JSON-RPC over HTTP
Internal automations that need tool discovery before execution

Common request flow

Most integrations follow the same sequence, even if the client handles some of it for you.

Use the MCP endpoint

Send JSON-RPC requests to the root MCP endpoint. If your client requests server-sent events with the Accept header set to text/event-stream, the same endpoint returns SSE-formatted responses.

A successful initialize call confirms that the client and server can speak the same protocol version. After that, call tools/list to discover tool schemas before attempting any authenticated tool execution.

Request server-sent events

Use SSE when your MCP client expects event: message frames instead of a plain JSON body.

curl -X POST "{API_BASE_URL}/mcp-server" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": "ping_001",
    "method": "ping",
    "params": {}
  }'

const response = await fetch("{API_BASE_URL}/mcp-server", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Accept": "text/event-stream"
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: "ping_001",
    method: "ping",
    params: {}
  })
})

const text = await response.text()
console.log(text)

The event payload is formatted as event: message followed by data: and the JSON-RPC response body.

Authenticate tool calls

Authenticate tools/call with either a NomadFiling API key or an OAuth 2.1 access token. Both authentication methods use the Authorization header with the Bearer scheme.

Supported authentication methods

Use an API key when you control the integration and do not need an end-user OAuth consent flow. API keys use the nf_ prefix, and the server verifies a SHA-256 hash against stored key records.

authorizationHeaderstring

Authorization: Bearer nf_example_9xmk7q2r4b7m8n2p6t1v5c8a

verificationstring

The server hashes the presented token with SHA-256 and compares it against api_keys.key_hash.

expirystring

Configurable per key.

usageTrackingstring

Successful authentication updates last_used_at.

If you send tools/call without valid credentials, the server returns HTTP 401 and includes a WWW-Authenticate header. Handle that response as an authentication challenge, not as a tool-level failure.

Example authenticated tool call

This example shows the pattern for invoking a tool after discovery. Replace the tool name and arguments with a real tool from /api/mcp-tools.

A successful tool result includes both a text payload and structuredContent. Tool-level failures use an error-shaped tool payload, while protocol-level failures use JSON-RPC errors.

Understand the available endpoints

The MCP server exposes both the main JSON-RPC channel and OAuth discovery endpoints.

OAuth and MCP endpoints

path

/.well-known/oauth-protected-resourceGET

Required

Returns OAuth protected resource metadata as defined by RFC 9728.

path

/.well-known/oauth-authorization-serverGET

Required

Returns OAuth 2.1 authorization server metadata.

path

/.well-known/openid-configurationGET

Required

Returns the same authorization server metadata through an OpenID configuration-style path.

path

/registerPOST

Required

Registers OAuth clients dynamically using RFC 7591.

path

/authorizeGET

Required

Starts the authorization flow and redirects to https://app.nomadfiling.com/oauth/authorize.

path

/approvePOST

Required

Approves OAuth consent in a frontend-facing flow that uses the signed-in user's JWT.

path

/tokenPOST

Required

Issues tokens for the authorization_code and refresh_token grants.

path

/POST

Required

Handles MCP JSON-RPC requests and supports SSE responses.

CORS behavior

Browser-based clients can call the server directly. The function returns permissive CORS headers and responds to OPTIONS preflight requests with status 200 and headers only.

Access-Control-Allow-Originstring

*

Access-Control-Allow-Methodsstring

GET, POST, OPTIONS, DELETE

Access-Control-Allow-Headersstring

authorization, x-client-info, apikey, content-type, mcp-session-id, mcp-protocol-version

Access-Control-Expose-Headersstring

mcp-session-id, www-authenticate

JSON-RPC methods and behavior

The server implements a focused MCP method set. Some methods are informational, while tools/call executes authenticated actions.

Supported methods

initializemethod

No authentication required. Returns protocolVersion, capabilities, serverInfo, and instructions.

pingmethod

No authentication required. Returns an empty object.

notifications/initializedmethod

No authentication required. Returns HTTP 202.

notifications/cancelledmethod

No authentication required. Returns HTTP 202.

tools/listmethod

No authentication required. Returns all tool schemas.

tools/callmethod

Authentication required. Dispatches execution to the named tool.

resources/listmethod

Returns an empty result.

prompts/listmethod

Returns an empty result.

Error handling

Use HTTP status and JSON-RPC error codes together. Parse failures happen before method dispatch, while authorization failures happen when a protected tool request reaches the server.

Condition	HTTP status	JSON-RPC code	Meaning
Invalid JSON body	400	-32700	Parse error
Unknown method	200	-32601	Method not found
Unauthenticated protected tool call	401	-32001	Unauthorized

Tool response shape

Successful tool execution returns MCP content plus a structured payload your client can parse directly.

contentarray

Required

An array of message parts. Successful tool responses include a text item whose text field contains a JSON string.

content[].typestring

Required

For current tool responses, the value is text.

content[].textstring

Required

A human-readable or serialized JSON payload.

structuredContentobject

Required

A machine-readable representation of the same result.

When a tool fails at the application layer, the server returns an MCP tool error payload instead of a successful structuredContent result.

isErrorboolean

Required

Set to true for tool-level failures.

contentarray

Required

Contains at least one text message describing the error.

Token formats and lifetimes

Token prefixes help clients distinguish the credential type before sending a request. The server stores sensitive token material as SHA-256 hashes rather than raw secrets.

Credential inventory

Credential	Prefix	Lifetime
API key	`nf_`	Configurable
OAuth client ID	`mcp_client_`	Permanent
OAuth client secret	`mcp_secret_`	Permanent
Authorization code	`mcp_code_`	5 minutes
Access token	`mcp_at_`	1 hour
Refresh token	`mcp_rt_`	30 days

Recommended integration pattern

Call get_form_schema before create_filing. That sequence matches the server instructions and reduces tool-call failures caused by missing or malformed filing fields.

Initialize the connection

Send initialize to confirm the protocol version and capture the returned server metadata.

Your client is ready for discovery when the response includes protocolVersion set to 2025-06-18 and serverInfo.name set to nomadfiling-mcp.

Discover tools

Call tools/list without authentication if your client supports anonymous discovery, or with authentication if your integration prefers a single authenticated channel.

Success looks like a JSON-RPC result containing the available tool definitions.

Fetch the form schema

Call tools/call with the get_form_schema tool before submitting data.

Success looks like a tool result with structuredContent that describes the expected filing shape for the selected form.

Create the filing

Call tools/call again with create_filing and a payload that matches the schema you just retrieved.

A successful submission returns an MCP tool result rather than a protocol error.

Frequently asked questions

Authentication

MCP tools

Manage API keys

Form 5472 and 1120 filings

For partnership workflows, see Partnership filing.

Was this page helpful?

MCP server overview

Connect agents to the Nomadfiling MCP server

Server identity

What the server is for

Common request flow

Use the MCP endpoint

Request server-sent events

Authenticate tool calls

Supported authentication methods

Example authenticated tool call

Understand the available endpoints

OAuth and MCP endpoints

CORS behavior

JSON-RPC methods and behavior

Supported methods

Error handling

Tool response shape

Token formats and lifetimes

Credential inventory

Recommended integration pattern

Frequently asked questions

Related pages