@synapse-network-ai/mcp-server

SynapseNetwork MCP Server

Official Model Context Protocol (MCP) stdio server for SynapseNetwork. It gives Cursor, Claude Desktop, Devin, and MCP-compatible agent frameworks a stateless way to discover external APIs, invoke them, and retrieve receipts through SynapseNetwork agent payments.

Website: https://www.synapse-network.ai/

SynapseNetwork is AgentPay infrastructure: agents discover services, pay for API calls with USDC micropayments through the Gateway, and receive auditable receipts. This MCP package is intentionally a thin runtime adapter. It does not own settlement, custody, pricing memory, provider setup, deposits, withdrawals, or admin workflows.

Related packages

This MCP server is the agent-tool adapter published as @synapse-network-ai/mcp-server. It does not import the Synapse SDK.

Use the official SDK repository when you want application code instead of MCP tools:

• SDK source: https://github.com/SynapseNetworkAI/Synapse-Network-Sdk
• TypeScript SDK: https://www.npmjs.com/package/@synapse-network-ai/sdk/v/1.0.0
• Python SDK: https://pypi.org/project/synapse-network-ai-sdk/1.0.0/
• Go SDK: https://pkg.go.dev/github.com/SynapseNetworkAI/Synapse-Network-Sdk/go@v1.0.0
• Java SDK: https://repo1.maven.org/maven2/ai/synapse-network/synapse-network-sdk/1.0.0/
• .NET SDK: https://www.nuget.org/packages/SynapseNetwork.Sdk/1.0.0

Why This Exists

Agents should not need to memorize SDK code, pricing rules, or HTTP routes. Humans configure this MCP server once, then agents get three tools:

discover_services -> invoke_and_pay -> get_receipt

The server is intentionally small and stateless:

• No in-memory discovery cache.
• No local persistence.
• No Synapse SDK import.
• No owner, admin, or provider control-plane tools.
• Direct Gateway HTTP calls with native fetch.
• Money values stay decimal strings at every boundary.

Quick Start

Use npx from an MCP client:

npx -y @synapse-network-ai/mcp-server

Or install globally for manual testing:

npm install -g @synapse-network-ai/mcp-server
synapse-mcp-server --help

Required credential:

export SYNAPSE_AGENT_KEY=agt_xxx

Optional runtime settings:

export SYNAPSE_ENV=prod           # prod for production workflows; staging is for preview/E2E
export SYNAPSE_GATEWAY_URL=...    # advanced custom Gateway override
export SYNAPSE_TIMEOUT_MS=30000

Credential aliases are accepted for compatibility: SYNAPSE_API_KEY and SYNAPSE_AGENT_TOKEN. New integrations should use SYNAPSE_AGENT_KEY. Use SYNAPSE_ENV=prod for production Agent workflows. Use staging only for preview validation and live smoke tests.

Claude Desktop

Add the server to claude_desktop_config.json:

{
  "mcpServers": {
    "synapse-agentpay": {
      "command": "npx",
      "args": ["-y", "@synapse-network-ai/mcp-server"],
      "env": {
        "SYNAPSE_AGENT_KEY": "agt_xxx",
        "SYNAPSE_ENV": "prod"
      }
    }
  }
}

Restart Claude Desktop. The agent should then see discover_services, invoke_and_pay, and get_receipt.

Cursor

Add an MCP server with the same command and environment:

{
  "command": "npx",
  "args": ["-y", "@synapse-network-ai/mcp-server"],
  "env": {
    "SYNAPSE_AGENT_KEY": "agt_xxx",
    "SYNAPSE_ENV": "prod"
  }
}

Once configured, ask Cursor to discover Synapse services before invoking paid APIs.

Other MCP Clients

Most MCP clients do not require a separate Synapse-specific plugin. They launch this npm package as a stdio MCP server and pass an Agent Key in the environment.

VS Code / GitHub Copilot workspace-style config:

{
  "servers": {
    "synapse-agentpay": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@synapse-network-ai/mcp-server"],
      "env": {
        "SYNAPSE_AGENT_KEY": "agt_xxx",
        "SYNAPSE_ENV": "prod"
      }
    }
  }
}

Windsurf, Cline, Roo Code, Zed, Devin, and other MCP-compatible clients should use the same command, args, and environment variables when they support stdio MCP servers.

MCP Tools

discover_services

Searches SynapseNetwork services through:

POST /api/v1/agent/discovery/search

Inputs:

• query optional natural-language service intent.
• tags optional tag filters.
• limit optional result limit, max 50.
• sort optional: best_match, lowest_price, fastest, highest_reliability.

Outputs include agent-facing service metadata, schemas, health, and pricing fields such as priceUsdc for fixed-price APIs or token-metered pricing fields for LLM services. Provider payout, ledger, internal routing, and settlement internals are not exposed.

invoke_and_pay

Invokes a service through:

POST /api/v1/agent/invoke

Inputs:

• service_id required service id from discover_services.
• payload required JSON payload for the provider service.
• costUsdc fixed-price USDC decimal string copied exactly from discovery.
• idempotencyKey stable task-level idempotency key.
• maxCostUsdc optional decimal string cap for token-metered or LLM services.
• requestId optional trace id.
• responseMode optional, usually sync.

For fixed-price APIs, costUsdc must match the discovered price. If the price is stale or copied incorrectly, Gateway returns PRICE_MISMATCH; rediscover and retry only if the user or task permits the current price.

For token-metered LLM services, omit costUsdc and pass maxCostUsdc when a budget cap is needed. Gateway remains the source of truth for holds, charges, risk, settlement, and receipts.

get_receipt

Fetches invocation status and receipt through:

GET /api/v1/agent/invocations/{invocation_id}

Input:

• invocation_id returned by invoke_and_pay.

Gateway enforces that the receipt belongs to the configured Agent Key.

Agent Usage Rules

• Call discover_services before invoke_and_pay.
• For fixed-price APIs, copy the observed price into costUsdc exactly as a string.
• Never convert USDC values to JavaScript numbers or floating-point values for business logic.
• Provide a stable idempotencyKey for each task when possible.
• After invocation, call get_receipt and inspect status and charged amount fields.
• On PRICE_MISMATCH, rediscover and retry with the updated price only if permitted.
• On balance, budget, credential, or forbidden errors, stop and ask the owner to fix Agent Key state.
• Treat this MCP server as stateless across process restarts.

Security Boundary

This package uses only an Agent Key:

SYNAPSE_AGENT_KEY=agt_xxx

It must never request, store, log, document, or generate code that asks for:

• Owner private keys or seed phrases.
• Owner JWTs or wallet signing authority.
• Provider secrets or provider setup permissions.
• Admin credentials or internal service tokens.
• Deposit, withdrawal, refund, or settlement permissions.

If an issue, PR, prompt, or generated snippet asks for any of those capabilities, treat it as out of scope for this MCP server.

E2E Verification

The default open-source verification path does not require credentials or a Synapse Gateway.

Protocol-only E2E with a mock Gateway:

npm run verify:mcp

This checks type safety, unit tests, build output, MCP stdio tool discovery, and the full mock flow:

discover_services -> invoke_and_pay -> get_receipt

Remote MCP protocol smoke with a mock Gateway:

npm run test:e2e:remote:mock

This starts the hosted HTTP entrypoint locally and verifies:

• POST /mcp Streamable HTTP with bearer auth.
• GET /mcp/sse plus POST /mcp/messages legacy HTTP+SSE compatibility.
• Public unauthenticated GET /healthz and GET /readyz.
• 401 plus WWW-Authenticate metadata on unauthenticated MCP calls.

Preview And Staging E2E

Use staging only for preview validation and live E2E smoke tests. Do not use staging for production Agent workflows.

export SYNAPSE_ENV=staging

npm run test:e2e:staging

For SynapseNetwork maintainers, staging E2E reads SYNAPSE_AGENT_KEY from Google Secret Manager by default using the synapse-staging-e2e-agent-credential secret. Set SYNAPSE_E2E_SECRET_PROJECT when the active gcloud project is not the staging secrets project.

Developers who are not using SynapseNetwork's GCP project can force a local Agent Key:

export SYNAPSE_E2E_AGENT_KEY_SOURCE=env
export SYNAPSE_AGENT_KEY=agt_xxx
export SYNAPSE_ENV=staging

npm run test:e2e:staging

By default, staging E2E performs broad discovery with sort=lowest_price, then selects a free fixed-price service by inspecting price fields. SYNAPSE_E2E_QUERY is optional and should be a real service intent such as oss, weather, or sentiment, not a price filter. The script refuses paid invokes unless explicitly allowed.

Specified staging service:

export SYNAPSE_ENV=staging
export SYNAPSE_E2E_SERVICE_ID=svc_quotes_famous_top3
export SYNAPSE_E2E_PAYLOAD_JSON='{"topic":"agent payments"}'
export SYNAPSE_E2E_COST_USDC='0.000000'

npm run test:e2e:staging

Token-metered staging service:

export SYNAPSE_ENV=staging
export SYNAPSE_E2E_SERVICE_ID=svc_deepseek_chat
export SYNAPSE_E2E_PAYLOAD_JSON='{"messages":[{"role":"user","content":"hello"}],"max_tokens":32}'
export SYNAPSE_E2E_MAX_COST_USDC='0.100000'

npm run test:e2e:staging

Production E2E

Production E2E requires a production Agent Key, must be run intentionally, and must not run in default CI.

export SYNAPSE_AGENT_KEY=agt_prod_xxx
export SYNAPSE_ENV=prod
export SYNAPSE_E2E_SERVICE_ID=svc_prod_smoke
export SYNAPSE_E2E_COST_USDC='0.000000'

npm run test:e2e:prod

Troubleshooting

Missing Synapse agent key: set SYNAPSE_AGENT_KEY=agt_xxx in the MCP client environment.

SYNAPSE_AGENT_KEY must start with agt_: use an Agent runtime credential, not an owner token or wallet secret.

PRICE_MISMATCH: call discover_services again and copy the current price string into costUsdc.

INSUFFICIENT_BALANCE, budget, or credential errors: stop and ask the owner to adjust funding, budget, or Agent Key settings.

No services in staging discovery during preview testing: confirm the Agent Key can access staging and try a broader query or no query.

Tool does not appear in the MCP client: run npm run build, restart the MCP client, and confirm the configured command uses npx -y @synapse-network-ai/mcp-server or the built dist/index.js.

Development

npm install
npm run typecheck
npm test
npm run build
npm run test:e2e:mock
npm run test:e2e:remote:mock
npm run ci:quality
npm pack --dry-run

Release readiness check:

npm run release:readiness

CI runs npm run verify:mcp, npm run smoke:cli, npm run ci:quality, and npm pack --dry-run.

Quality gates enforce named public object return contracts, size budgets, complexity budgets, duplicate-code detection, and justified suppression comments. See CONTRIBUTING.md for the full contributor workflow.

Agent Skills And Rules

MCP tools are the runtime capability surface. Skills and rules are optional instruction packs that help agents use those tools correctly.

This repository includes reusable templates:

• Claude Skill: skills/claude/synapse-agentpay/SKILL.md
• Cursor Rule: skills/cursor/synapse-agentpay.mdc
• Codex Skill: skills/codex/synapse-agentpay/SKILL.md

These files teach agents to use production MCP config, call discover_services -> invoke_and_pay -> get_receipt, keep money as strings, rediscover on PRICE_MISMATCH, and stay inside the Agent Key security boundary.

Open Source Community

• Contributing: CONTRIBUTING.md
• Security policy: SECURITY.md
• Support: SUPPORT.md
• Code of conduct: CODE_OF_CONDUCT.md
• Changelog: CHANGELOG.md
• License: MIT

MCP Registry Publishing

The repo includes server.json for the MCP Registry publisher flow. It publishes both the npm stdio package and the hosted Remote MCP endpoint:

• stdio package: npx -y @synapse-network-ai/mcp-server
• Remote MCP: https://mcp.synapse-network.ai/mcp
• Remote auth: Authorization: Bearer agt_xxx

After publishing the npm package:

npm run release:readiness
npm publish --access public --registry=https://registry.npmjs.org
npm view @synapse-network-ai/mcp-server --registry=https://registry.npmjs.org
npx -y @synapse-network-ai/mcp-server --help
mcp-publisher login github
mcp-publisher publish

The registry hosts metadata; npm hosts the package artifact. Remote MCP remains a hosted BYOK channel: customers pass their own Agent Key as the bearer token.

MCP Directory Submissions

After npm and the official MCP Registry entry are live, submit the same production metadata to community discovery surfaces:

• Smithery: publish/import the public MCP URL when supported, otherwise use the GitHub/npm package metadata.
• Glama MCP Directory: submit the GitHub repository and use the Inspector against the Remote MCP URL with a bearer Agent Key.
• PulseMCP.
• mcp.so / MCP.so.
• awesome-mcp-servers and related community lists.

Use the package name @synapse-network-ai/mcp-server, the hosted endpoint https://mcp.synapse-network.ai/mcp, the website https://www.synapse-network.ai/, and the MCP registry name io.github.synapsenetworkai/synapse-network-mcp-server. Public listings should describe staging only as preview/E2E validation, not as the default Agent workflow.

Detailed launch copy and submission checklist: docs/launch/mcp-and-skills-registration.md.

Remote MCP Hosted Endpoint

The default package remains a stdio MCP server for local MCP clients. For cloud-hosted app surfaces such as OpenAI Remote MCP, Claude MCP connector, Apps SDK, or managed-agent connector flows, run the hosted HTTP entrypoint:

npm run build
SYNAPSE_MCP_HTTP_HOST=0.0.0.0 \
SYNAPSE_MCP_HTTP_PORT=3000 \
SYNAPSE_MCP_PUBLIC_BASE_URL=https://mcp.synapse-network.ai \
SYNAPSE_GATEWAY_URL=https://api.synapse-network.ai \
SYNAPSE_REMOTE_AUTH_MODE=agent_key \
npm run start:http

Remote endpoint map:

• POST /mcp and GET /mcp: Streamable HTTP MCP transport.
• GET /mcp/sse: legacy HTTP+SSE connection endpoint for OpenAI/Claude compatibility.
• POST /mcp/messages: legacy HTTP+SSE JSON-RPC message endpoint.
• GET /healthz and GET /readyz: public lightweight probes, never OAuth-gated.
• GET /.well-known/oauth-protected-resource: OAuth protected-resource metadata.

Remote auth modes:

• SYNAPSE_REMOTE_AUTH_MODE=agent_key: public bring-your-own-Agent-Key mode. Authorization: Bearer agt_xxx maps directly to Gateway X-Credential, so each customer pays from their own Agent balance. Do not configure SYNAPSE_AGENT_KEY or SYNAPSE_REMOTE_BEARER_TOKEN on the public hosted endpoint.
• SYNAPSE_REMOTE_AUTH_MODE=oauth: validates OAuth JWTs with SYNAPSE_OAUTH_ISSUER, SYNAPSE_OAUTH_JWKS_URL, and SYNAPSE_OAUTH_AUDIENCE, then maps the verified token to the configured downstream SYNAPSE_AGENT_KEY.

Remote MCP exposes the same three stateless tools and the same security boundary. External OpenAI/Claude/OAuth tokens are never forwarded to Synapse Gateway. For paid invoke_and_pay, configure OpenAI/Claude with a human approval step unless the target provider is an explicit free smoke service.

ChatGPT workspace custom app registration:

• In ChatGPT Business, Enterprise, or Edu, enable developer mode for the workspace/user.
• Create a custom app with MCP endpoint https://mcp.synapse-network.ai/mcp.
• Use bearer/API-token authentication with agt_xxx as the secret credential when the UI supports static bearer tokens.
• Scan tools and verify discover_services imports. Keep invoke_and_pay behind human approval/action confirmation.
• If the workspace requires OAuth/OIDC instead of static bearer credentials, treat that as an OAuth wrapper follow-up; do not weaken Remote MCP auth.

Cloud Run note: if using /mcp/sse, enable Session Affinity so /mcp/messages returns to the instance holding the SSE transport. Prefer /mcp Streamable HTTP for newer clients.

Production Cloud Run deployment and OpenAI Remote MCP smoke steps are documented in docs/launch/remote-mcp-gcloud-openai.md. Maintainers can deploy the hosted endpoint with:

PROJECT_ID=<gcp-project-id> npm run deploy:gcloud:remote