{
  "schema_version": "agentpmt.docs.v1",
  "generated_at": "2026-08-18T18:03:14.688Z",
  "release_id": "5367fe2ce2aa1968ba089b7a77934459c60b1659a1b8fa753f18f40c1cf609fa",
  "id": "generated-mcp-connection",
  "page_url": "https://www.agentpmt.com/docs/mcp-reference/connection",
  "markdown_url": "https://www.agentpmt.com/docs/mcp-reference/connection?format=agent-md",
  "json_url": "https://www.agentpmt.com/docs/mcp-reference/connection?format=agent-json",
  "source_path": "content/docs/connection.mdoc",
  "updated_at": "2026-08-14T05:15:40.324Z",
  "headings": [
    {
      "depth": 2,
      "id": "prerequisites",
      "title": "Prerequisites"
    },
    {
      "depth": 2,
      "id": "hosted-streamable-https-endpoint",
      "title": "Hosted Streamable HTTPS Endpoint"
    },
    {
      "depth": 2,
      "id": "complete-hosted-config-examples",
      "title": "Complete Hosted Config Examples"
    },
    {
      "depth": 2,
      "id": "local-stdio-fallback",
      "title": "Local STDIO Fallback"
    },
    {
      "depth": 2,
      "id": "platform-specific-local-config-examples",
      "title": "Platform-Specific Local Config Examples"
    },
    {
      "depth": 2,
      "id": "browser-based-clients",
      "title": "Browser-Based Clients"
    },
    {
      "depth": 2,
      "id": "postman-testing",
      "title": "Postman Testing"
    },
    {
      "depth": 2,
      "id": "troubleshooting",
      "title": "Troubleshooting"
    },
    {
      "depth": 2,
      "id": "discovery-and-protocol-reference",
      "title": "Discovery and Protocol Reference"
    },
    {
      "depth": 2,
      "id": "mcp-endpoint",
      "title": "MCP Endpoint"
    },
    {
      "depth": 2,
      "id": "native-mcp-methods",
      "title": "Native MCP Methods"
    },
    {
      "depth": 2,
      "id": "fetch-native-tools-and-call-them",
      "title": "Fetch Native Tools And Call Them"
    },
    {
      "depth": 3,
      "id": "1-initialize",
      "title": "1) Initialize"
    },
    {
      "depth": 3,
      "id": "2-list-current-native-tools",
      "title": "2) List current native tools"
    },
    {
      "depth": 3,
      "id": "3-call-a-tool-returned-by-toolslist",
      "title": "3) Call a tool returned by tools/list"
    },
    {
      "depth": 2,
      "id": "get-more-tools",
      "title": "Get More Tools"
    },
    {
      "depth": 3,
      "id": "1-browse-available-external-tools",
      "title": "1) Browse available external tools"
    },
    {
      "depth": 3,
      "id": "2-create-an-auth-session-for-wallet-signing",
      "title": "2) Create an auth session for wallet signing"
    },
    {
      "depth": 3,
      "id": "3-invoke-a-selected-tool",
      "title": "3) Invoke a selected tool"
    },
    {
      "depth": 2,
      "id": "well-known-discovery-urls",
      "title": "Well-Known Discovery URLs"
    },
    {
      "depth": 2,
      "id": "related-api-reference-links",
      "title": "Related API Reference Links"
    }
  ],
  "related_products": [],
  "related_workflows": [],
  "related_agents": [],
  "doc": {
    "title": "Connection",
    "description": "Connect MCP clients to AgentPMT with hosted Streamable HTTPS or the local STDIO fallback.",
    "category": "MCP Reference",
    "image": null,
    "full_path": "mcp-reference/connection",
    "body_markdown": "# Connection\n\nAgentPMT exposes one MCP server for your Agent Group. Use the hosted Streamable HTTPS endpoint when your client supports remote MCP. Use the local STDIO router when your client requires a command-based MCP server.\n\nAn Agent Group Bearer token authorizes calls for one Agent Group. Keep it in the client secret field or environment configuration, never in prompts, shared instructions, screenshots, or source control. Rotate it if it may have been exposed.\n\nThe tools, credentials, spending caps, and activity log for that group define what the connected agent can do.\n\n## Prerequisites\n\n### Create or choose an Agent Group\n\nIn the dashboard, open **Control Center -> Agent Groups**. Add the tools and workflows this agent may use, bind required credentials, and set spend controls.\n\n### Copy the Bearer token\n\nClick **Show Bearer Token** on the group card. Treat the token like a password; it authorizes every MCP call for that group.\n\n![AgentPMT Agent Group card showing the Show Bearer Token action used to reveal the token](https://www.agentpmt.com/docs-assets/images/screenshots/mcp-connection/find-bearer-token.f50c17e96e9a.png)\n\n_Click Show Bearer Token on the group card to reveal the token for your client config._\n\n### Choose a transport\n\nPrefer hosted Streamable HTTPS for remote-MCP clients. Choose local STDIO only when the client needs a local command.\n\n## Hosted Streamable HTTPS Endpoint\n\n```text\nEndpoint:  https://api.agentpmt.com/mcp\nTransport: Streamable HTTP over HTTPS\nAuth:      Authorization: Bearer <AGENTPMT_BEARER_TOKEN>\n```\n\nHosted MCP does not require a local package. Your client connects directly to AgentPMT over HTTPS, sends the Bearer token in config or a secret field, and receives the current tool catalog for the agent group.\n\n## Complete Hosted Config Examples\n\nUse this generic shape for MCP clients that accept remote Streamable HTTP servers in a config file:\n\n```json\n{\n  \"mcpServers\": {\n    \"agentpmt\": {\n      \"type\": \"streamable-http\",\n      \"url\": \"https://api.agentpmt.com/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer <AGENTPMT_BEARER_TOKEN>\",\n        \"x-instance-metadata\": \"{\\\"client\\\":\\\"generic-mcp\\\",\\\"platform\\\":\\\"remote\\\"}\"\n      }\n    }\n  }\n}\n```\n\n`x-instance-metadata` is optional. When your client supports custom headers, use it to identify the client and platform in activity logs.\n\n### Cursor / Windsurf / VS Code\n\nIf your editor build exposes a remote MCP server option, use the hosted config shape above and set:\n\n```text\nURL: https://api.agentpmt.com/mcp\nAuthorization: Bearer <AGENTPMT_BEARER_TOKEN>\n```\n\nIf the editor only accepts command-based MCP servers, use the local STDIO fallback below.\n\n### ChatGPT / Claude browser clients\n\nBrowser-based clients usually store remote connector settings in the UI instead of a local file.\n\n```text\nServer URL: https://api.agentpmt.com/mcp\nAuthentication: Bearer token\nBearer token: <AGENTPMT_BEARER_TOKEN>\n```\n\nUse the client secret field for the Bearer token when one is available. Do not paste the token into public instructions, shared prompts, or browser-visible page content.\n\n### Postman MCP\n\nCreate a new MCP request in Postman and use the hosted endpoint as the request URL:\n\n```text\nURL: https://api.agentpmt.com/mcp\nHeader: Authorization: Bearer <AGENTPMT_BEARER_TOKEN>\nOptional header: x-instance-metadata: {\"client\":\"postman\",\"platform\":\"desktop\"}\n```\n\nConnect the request, inspect the loaded tools, run a simple tool call, then verify the call under **Control Center -> Agent Activity**.\n\n## Local STDIO Fallback\n\nInstall the local router when your MCP client requires a command. The router does not execute tools locally. It reads `AGENTPMT_BEARER_TOKEN`, receives JSON-RPC over STDIO, and forwards requests to `https://api.agentpmt.com/mcp`.\n\n```bash\nnpm install -g @agentpmt/mcp-router\nagentpmt-setup\n```\n\nThe setup command detects supported clients, asks for the Bearer token, and writes the appropriate config. Re-run `agentpmt-setup` when you switch agent groups or add another local client.\n\n## Platform-Specific Local Config Examples\n\nUse these blocks only for clients that need a local command. Keep `AGENTPMT_BEARER_TOKEN` in the config file or the client secret store. `X_INSTANCE_METADATA` is optional and must be a JSON string.\n\n### Claude Desktop\n\nConfig files:\n\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Linux: `~/.config/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"agentpmt\": {\n      \"command\": \"npx\",\n      \"args\": [\"--package=@agentpmt/mcp-router@latest\", \"agentpmt-router\"],\n      \"env\": {\n        \"AGENTPMT_BEARER_TOKEN\": \"<AGENTPMT_BEARER_TOKEN>\",\n        \"X_INSTANCE_METADATA\": \"{\\\"client\\\":\\\"claude_desktop\\\",\\\"platform\\\":\\\"desktop\\\"}\"\n      }\n    }\n  }\n}\n```\n\n### Claude Code\n\nUse the command-based MCP config when your Claude Code build does not expose hosted Streamable HTTPS settings.\n\n```json\n{\n  \"mcpServers\": {\n    \"agentpmt\": {\n      \"command\": \"npx\",\n      \"args\": [\"--package=@agentpmt/mcp-router@latest\", \"agentpmt-router\"],\n      \"env\": {\n        \"AGENTPMT_BEARER_TOKEN\": \"<AGENTPMT_BEARER_TOKEN>\",\n        \"X_INSTANCE_METADATA\": \"{\\\"client\\\":\\\"claude_code\\\",\\\"platform\\\":\\\"cli\\\"}\"\n      }\n    }\n  }\n}\n```\n\n### Cursor\n\nConfig file: `~/.cursor/mcp.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"agentpmt\": {\n      \"command\": \"npx\",\n      \"args\": [\"--package=@agentpmt/mcp-router@latest\", \"agentpmt-router\"],\n      \"env\": {\n        \"AGENTPMT_BEARER_TOKEN\": \"<AGENTPMT_BEARER_TOKEN>\",\n        \"X_INSTANCE_METADATA\": \"{\\\"client\\\":\\\"cursor\\\",\\\"platform\\\":\\\"desktop\\\"}\"\n      }\n    }\n  }\n}\n```\n\nAfter saving, open Cursor Settings -> Features -> MCP and refresh servers.\n\n### VS Code\n\nConfig files:\n\n- Windows: `%APPDATA%\\Code\\User\\mcp.json`\n- macOS: `~/Library/Application Support/Code/User/mcp.json`\n- Linux: `~/.config/Code/User/mcp.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"agentpmt\": {\n      \"command\": \"npx\",\n      \"args\": [\"--package=@agentpmt/mcp-router@latest\", \"agentpmt-router\"],\n      \"env\": {\n        \"AGENTPMT_BEARER_TOKEN\": \"<AGENTPMT_BEARER_TOKEN>\",\n        \"X_INSTANCE_METADATA\": \"{\\\"client\\\":\\\"vscode\\\",\\\"platform\\\":\\\"desktop\\\"}\"\n      }\n    }\n  }\n}\n```\n\n### Windsurf\n\nConfig file: `~/.codeium/windsurf/mcp_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"agentpmt\": {\n      \"command\": \"npx\",\n      \"args\": [\"--package=@agentpmt/mcp-router@latest\", \"agentpmt-router\"],\n      \"env\": {\n        \"AGENTPMT_BEARER_TOKEN\": \"<AGENTPMT_BEARER_TOKEN>\",\n        \"X_INSTANCE_METADATA\": \"{\\\"client\\\":\\\"windsurf\\\",\\\"platform\\\":\\\"desktop\\\"}\"\n      }\n    }\n  }\n}\n```\n\n### Zed\n\nConfig files:\n\n- Windows: `%APPDATA%\\Zed\\settings.json`\n- macOS/Linux: `~/.config/zed/settings.json`\n\n```json\n{\n  \"context_servers\": {\n    \"agentpmt\": {\n      \"settings\": {},\n      \"command\": {\n        \"path\": \"npx\",\n        \"args\": [\"--package=@agentpmt/mcp-router@latest\", \"agentpmt-router\"],\n        \"env\": {\n          \"AGENTPMT_BEARER_TOKEN\": \"<AGENTPMT_BEARER_TOKEN>\",\n          \"X_INSTANCE_METADATA\": \"{\\\"client\\\":\\\"zed\\\",\\\"platform\\\":\\\"desktop\\\"}\"\n        }\n      }\n    }\n  }\n}\n```\n\n### Codex CLI\n\nConfig file: `~/.codex/config.toml`\n\n```toml\n[mcp_servers.agentpmt]\ncommand = \"npx\"\nargs = [\"--package=@agentpmt/mcp-router@latest\", \"agentpmt-router\"]\n\n[mcp_servers.agentpmt.env]\nAGENTPMT_BEARER_TOKEN = \"<AGENTPMT_BEARER_TOKEN>\"\nX_INSTANCE_METADATA = '{\"client\":\"codex\",\"platform\":\"cli\"}'\n```\n\n### Gemini CLI\n\nConfig file: `~/.gemini/settings.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"agentpmt\": {\n      \"command\": \"npx\",\n      \"args\": [\"--package=@agentpmt/mcp-router@latest\", \"agentpmt-router\"],\n      \"env\": {\n        \"AGENTPMT_BEARER_TOKEN\": \"<AGENTPMT_BEARER_TOKEN>\",\n        \"X_INSTANCE_METADATA\": \"{\\\"client\\\":\\\"gemini\\\",\\\"platform\\\":\\\"cli\\\"}\"\n      }\n    }\n  }\n}\n```\n\n## Browser-Based Clients\n\nUse the hosted endpoint for browser clients that support remote MCP connectors. Store the Bearer token in the connector's secret/auth field, not in a chat message.\n\nIf the browser client does not support remote MCP, use AgentPMT's direct HTTP API from your own server-side runtime instead of exposing the Bearer token in client-side code.\n\n## Postman Testing\n\nPostman is useful for verifying an agent group before you rely on an agent prompt.\n\n### Create an MCP request\n\nChoose Postman's MCP request type and set the URL to `https://api.agentpmt.com/mcp`.\n\n### Add auth and metadata\n\nAdd `Authorization: Bearer <AGENTPMT_BEARER_TOKEN>`. Optionally add `x-instance-metadata: {\"client\":\"postman\",\"platform\":\"desktop\"}`.\n\n### Connect and run a tool\n\nConnect, choose one of the loaded tools, fill in the displayed parameters, and run the request.\n\n### Verify activity\n\nOpen **Control Center -> Agent Activity** and confirm the request, response, status, and metadata are logged.\n\n## Troubleshooting\n\n| Symptom | Check |\n| --- | --- |\n| No tools appear | Confirm the Bearer token belongs to the agent group you configured and that tools are added to that group. |\n| `401` or auth failure | Re-copy the Bearer token, remove extra whitespace, and check whether the token was rotated. |\n| Client rejects hosted config | Use the local STDIO fallback; that client likely requires a command-based MCP server. |\n| Tool is listed but fails | Bind any required credentials on the Agent Group and review the tool's current schema. |\n| Activity log is missing metadata | Confirm the client supports custom headers for hosted MCP or `X_INSTANCE_METADATA` for the local router. |\n## Discovery and Protocol Reference\n\n## MCP Endpoint\n\n- https://api.agentpmt.com/mcp\n\n## Native MCP Methods\n\n- `initialize`: Negotiates MCP protocol capabilities and starts a session.\n- `notifications/initialized`: Confirms client initialization after a successful initialize call.\n- `tools/list`: Returns the currently available native tool set for the authenticated context.\n- `tools/call`: Invokes a selected native tool by name with tool-specific arguments.\n\n## Fetch Native Tools And Call Them\n\n### 1) Initialize\n\n```bash\ncurl -X POST \"https://api.agentpmt.com/mcp\" \\\n  -H \"Authorization: Bearer <oauth_access_token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"method\": \"initialize\",\n  \"params\": {\n    \"protocolVersion\": \"2025-03-26\",\n    \"clientInfo\": {\n      \"name\": \"agentpmt-docs-example-client\",\n      \"version\": \"1.0.0\"\n    },\n    \"capabilities\": {\n      \"tools\": {}\n    }\n  }\n}'\n```\n\n### 2) List current native tools\n\n```bash\ncurl -X POST \"https://api.agentpmt.com/mcp\" \\\n  -H \"Authorization: Bearer <oauth_access_token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"method\": \"tools/list\",\n  \"params\": {}\n}'\n```\n\n### 3) Call a tool returned by tools/list\n\n```bash\ncurl -X POST \"https://api.agentpmt.com/mcp\" \\\n  -H \"Authorization: Bearer <oauth_access_token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"<tool_name_from_tools_list>\",\n    \"arguments\": {\n      \"example_input\": \"value\"\n    }\n  }\n}'\n```\n\n## Get More Tools\n\n### 1) Browse available external tools\n\n```bash\ncurl -X GET \"https://www.agentpmt.com/api/external/tools?limit=20\"\n```\n\n### 2) Create an auth session for wallet signing\n\n```bash\ncurl -X POST \"https://www.agentpmt.com/api/external/auth/session\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"wallet_address\": \"0xYOUR_WALLET\"\n  }'\n```\n\n### 3) Invoke a selected tool\n\n```bash\ncurl -X POST \"https://www.agentpmt.com/api/external/tools/<product_slug>/actions/<action_slug>/invoke\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"wallet_address\": \"0xYOUR_WALLET\",\n    \"session_nonce\": \"<session_nonce>\",\n    \"request_id\": \"<unique_request_id>\",\n    \"signature\": \"0x<wallet_signature>\",\n    \"parameters\": {\n      \"example\": \"value\"\n    }\n  }'\n```\n\n## Well-Known Discovery URLs\n\n- https://www.agentpmt.com/.well-known/mcp\n- https://www.agentpmt.com/.well-known/mcp/server.json\n- https://www.agentpmt.com/.well-known/mcp/server-card.json\n- https://www.agentpmt.com/mcp.json\n- https://www.agentpmt.com/.well-known/mcp.json\n- https://www.agentpmt.com/.well-known/glama.json\n- https://api.agentpmt.com/.well-known/mcp\n- https://api.agentpmt.com/.well-known/mcp/server.json\n- https://api.agentpmt.com/.well-known/mcp/server-card.json\n- https://api.agentpmt.com/mcp.json\n- https://api.agentpmt.com/.well-known/mcp.json\n- https://api.agentpmt.com/mcp/.well-known/mcp\n- https://api.agentpmt.com/.well-known/glama.json\n\n## Related API Reference Links\n\nRaw Bearer-token API callers should use [Programmatic Access](https://www.agentpmt.com/docs/api-reference/programmatic-access). Wallet-authenticated autonomous agents should use the [Autonomous Agents API](https://www.agentpmt.com/docs/api-reference/autonomous-agents). Agents paying for one eligible tool action with direct x402 should use [X402 Payments For Tool Usage](https://www.agentpmt.com/docs/autonomous-agents/x402-payments-for-tool-usage).\n\n### [API To MCP Tool Conversion](https://www.agentpmt.com/docs/agent-connections/api-to-mcp-tool-conversion)\n\nCreate a private Connected API tool, authorize it for an Agent Group, and call it over MCP.\n"
  }
}