MCP Server (stdio)

The @markdocket/cli package includes a built-in stdio MCP server that exposes MarkDocket's full tool catalog to any MCP-compatible AI host — such as Claude Desktop, Cursor, or any other client that speaks the Model Context Protocol over standard input/output.

Prerequisites

• Node.js 18 or later
• @markdocket/cli installed globally or available via npx
• A MarkDocket account and either a personal API key or a browser-OAuth session (created with markdocket login)

Connecting to an AI Host

Most MCP-compatible AI hosts accept an mcpServers configuration block. Point the command at markdocket mcp (or npx @markdocket/cli mcp if you prefer not to install globally).

Claude Desktop

Add the following to your Claude Desktop configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "markdocket": {
      "command": "markdocket",
      "args": ["mcp"],
      "env": {
        "MARKDOCKET_API_KEY": "your-personal-api-key"
      }
    }
  }
}

If you prefer browser OAuth login instead of an API key, omit the env block and run markdocket login once beforehand. The CLI stores the resulting session and uses it automatically when the MCP server starts.

Cursor and Other MCP Hosts

The pattern is the same for any host that supports stdio MCP servers:

Refer to your AI host's documentation for the exact configuration format.

Authentication Modes

The stdio MCP server supports two authentication modes that determine how tool calls are routed.

Personal API Key

Set the MARKDOCKET_API_KEY environment variable (or pass --api-key on the command line). Tool calls are authenticated with your personal API key and dispatched directly through the MarkDocket catalog.

Browser OAuth (OAuth 2.1)

Run markdocket login before starting the MCP server. This performs a full OAuth 2.1 PKCE flow — the CLI dynamically registers a short-lived OAuth client using RFC 7591, so no static client ID needs to be bundled with the package. Once authenticated, tool calls are routed through the hosted MCP endpoint using the OAuth access token.

How Tools Are Registered

The MCP server's tool list is derived entirely at runtime from the shared tool catalog — no tool names, schemas, or descriptions are hand-written in the MCP server itself.

When the server starts, it calls into the catalog to retrieve all externally available tools. Each tool carries:

• A unique name (e.g., trademark_search, patent_search)
• A JSON Schema describing its input parameters
• A human-readable description used in the MCP tool listing
• HTTP method and read/write metadata used to compute MCP annotations (see below)

Tools that are scoped to the internal agent loop (such as web_search and classify_goods) are excluded from the external catalog and therefore never appear in the stdio MCP server.

Because the MCP server reads the catalog at startup, any tool added to the MarkDocket platform automatically becomes available the next time the server process starts — no MCP-specific code changes are needed.

MCP Tool Annotations

The MCP protocol defines optional behavioral annotations that help AI hosts reason about how to use tools safely:

MarkDocket computes these annotations automatically from metadata already present on each tool definition — there is no hand-maintained annotation list.

How Annotations Are Derived

For every tool in the catalog, the MCP server applies the following logic:

• readOnlyHint is set to true when the tool's HTTP method is GET or the tool's definition carries a readOnly flag.
• idempotentHint is set to true for GET tools (reads are inherently idempotent) and for PUT tools (which follow REST idempotency conventions).
• destructiveHint is set to true when the tool name matches patterns associated with deletion or cancellation (for example, names containing delete, remove, or cancel), or when the HTTP method indicates a destructive operation.

Because the HTTP method and read/write intent are set once at the agent-tool layer, the same metadata drives both the API transport and the MCP behavioral semantics — a single source of truth for all surfaces.

Response Shaping and Size Limits

Before returning results to the MCP host, the server applies domain-aware response compaction to keep payloads within the 1 MB character limit:

• Polling tools (tools that check the status of a running job) have large intermediate fields stripped from their output — only status and progress information is returned.
• Final result tools return their full structured output.
• Full-report tools pass through unmodified.

If a response still exceeds the size limit after shaping, the server returns the first 150,000 characters as a preview and sets truncated: true in the result, rather than returning an error. This allows AI hosts to work with partial results and request the full report separately if needed.

Billing and Usage

Tools called through the MCP server consume MarkDocket credits or quota in the same way as tools called from the web app or the markdocket call CLI command. If your account does not have sufficient credit for a tool call, the server returns a structured billing error as an MCP isError: true result with a structuredContent payload describing the required action — for example, upgrading your plan or purchasing additional credits.

Troubleshooting

The MCP server starts but shows no tools. Verify your API key is valid or that you have an active markdocket login session. The tool catalog is fetched at startup; an auth failure results in an empty registry.

A tool call returns a billing error. Check your MarkDocket account's usage and plan limits. The structured error in the MCP result includes a requiredAction field indicating exactly what is needed.

Tool results are truncated. Large results are automatically preview-truncated to fit within MCP size limits. Use the corresponding full-report tool (if available for that workflow) to retrieve the complete output.

I added a tool but it does not appear in my AI host. Tool registration happens at server startup. Restart the MCP server process (or reload the AI host's MCP connection) to pick up newly added tools.