> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dzap.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Use DZap AI tools through MCP over stdio or streamable HTTP.

DZap MCP is exposed through both local and remote surfaces so agents can connect from desktop, IDE, browser, or server-side runtimes.

## Transport surfaces

1. Stdio server (`npm run mcp:dev` / `npm run mcp`)
2. Streamable HTTP transport (`POST|GET|DELETE /mcp`)

## Live endpoint

`https://nlp-ai-439689868940.europe-north1.run.app/mcp`

## Session behavior

* `initialize` creates a session
* follow-up requests include `mcp-session-id`
* `DELETE /mcp` closes session state

## Authentication (HTTP transport)

The `/mcp` HTTP endpoint is open by default (and logs a warning) for local use.
For any shared or public deployment, protect it with:

* `DZAP_MCP_HTTP_TOKEN` — when set, every `/mcp` request must include
  `Authorization: Bearer <token>` (compared in constant time).
* `DZAP_MCP_ALLOWED_ORIGINS` — optional comma-separated `Origin` allowlist that
  blocks drive-by browser callers.

The stdio transport is not network-exposed and needs no token.

## JSON-RPC error handling

Invalid method/tool/arguments return structured JSON-RPC errors:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "req-2",
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {
      "tool": "PerformZapTool",
      "field": "amount",
      "expected": "string"
    }
  }
}
```

Common error codes:

* `-32600` invalid request
* `-32601` method not found
* `-32602` invalid params
* `-32603` internal error

## Tool annotations

Each tool is registered with a `readOnlyHint` annotation so planners can route
safely. Read-only tools are `true`; the interactive execution tools
(`PerformZapTool`, `ChangeChainTool`) are `false`:

```json theme={null}
{
  "name": "BalanceTool",
  "description": "Fetch wallet balances",
  "annotations": {
    "readOnlyHint": true
  }
}
```

Treat `readOnlyHint: false` tools as execution-sensitive and require user
confirmation in the client UX.

## MCP resources and prompts

Resources:

* `dzap://tools/catalog`
* `dzap://prompts/system`
* `dzap://docs/urls`

Prompts:

* `wallet-overview`
* `tool-execution-plan`

## Remote config example

```json theme={null}
{
  "mcpServers": {
    "DZapAI": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://nlp-ai-439689868940.europe-north1.run.app/mcp"]
    }
  }
}
```

## Local run commands

```bash theme={null}
npm run mcp:dev
```

```bash theme={null}
npm run build
npm run mcp
```

## Library exports

* `createDzapMcpServer(...)`
* `startDzapMcpServer(...)`