SynapseNetwork MCP Server

Synapse Network MCP Server for paid API calls

Synapse Network MCP Server for paid API calls is the official Model Context Protocol (MCP) server from SynapseNetworkAI. "Synapse Network MCP" with a space and "SynapseNetwork MCP" without a space refer to this sameSynapseNetworkAI/Synapse-Network-MCP-Serverproject. It gives ChatGPT custom MCP apps, Claude connectors, 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/

discover_services -> invoke_and_pay -> get_receipt

- Remote MCP setup:https://docs.synapse-network.ai/mcp/paid-api-calls
- Brand disambiguation:https://docs.synapse-network.ai/mcp/brand-disambiguation

- 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

discover_services -> invoke_and_pay -> get_receipt

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

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

{ "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 seediscover_services,invoke_and_pay, andget_receipt.

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.

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.

Searches SynapseNetwork services through:

- queryoptional natural-language service intent.
- tagsoptional tag filters.
- limitoptional result limit, max 50.
- sortoptional:best_match,lowest_price,fastest,highest_reliability.

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

- service_idrequired service id fromdiscover_services.
- payloadrequired JSON payload for the provider service.
- costUsdcfixed-price USDC decimal string copied exactly from discovery.
- idempotencyKeystable task-level idempotency key.
- maxCostUsdcoptional decimal string cap for token-metered or LLM services.
- requestIdoptional trace id.
- responseModeoptional, usuallysync.

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

For token-metered LLM services, omitcostUsdcand passmaxCostUsdcwhen a budget cap is needed. Gateway remains the source of truth for holds, charges, risk, settlement, and receipts.

Fetches invocation status and receipt through:

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

- invocation_idreturned byinvoke_and_pay.

Gateway enforces that the receipt belongs to the configured Agent Key.
- Calldiscover_servicesbeforeinvoke_and_pay.
- For fixed-price APIs, copy the observed price intocostUsdcexactly as a string.
- Never convert USDC values to JavaScript numbers or floating-point values for business logic.
- Provide a stableidempotencyKeyfor each task when possible.
- After invocation, callget_receiptand inspectstatusand charged amount fields.
- OnPRICE_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.

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.

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

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:

This starts the hosted HTTP entrypoint locally and verifies:

- POST /mcpStreamable HTTP with bearer auth.
- GET /mcp/sseplusPOST /mcp/messageslegacy HTTP+SSE compatibility.
- Public unauthenticatedGET /healthzandGET /readyz.
- 401plusWWW-Authenticatemetadata on unauthenticated MCP calls.

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 readsSYNAPSE_AGENT_KEYfrom Google Secret Manager by default using thesynapse-staging-e2e-agent-credentialsecret. SetSYNAPSE_E2E_SECRET_PROJECTwhen the activegcloudproject 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 withsort=lowest_price, then selects a free fixed-price service by inspecting price fields.SYNAPSE_E2E_QUERYis optional and should be a real service intent such asoss,weather, orsentiment, not a price filter. The script refuses paid invokes unless explicitly allowed.

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

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 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

Missing Synapse agent key: setSYNAPSE_AGENT_KEY=agt_xxxin 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: calldiscover_servicesagain and copy the current price string intocostUsdc.

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: runnpm run build, restart the MCP client, and confirm the configured command usesnpx -y @synapse-network-ai/mcp-serveror the builtdist/index.js.

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

CI runsnpm run verify:mcp,npm run smoke:cli,npm run ci:quality, andnpm pack --dry-run.

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