Access & discovery

Remote MCP

Discover and call PerchanceAI tools over the POST JSON-RPC MCP endpoint.

Endpoint

POST/api/mcp

Authentication & scope

This ping example requires no bearer; business calls require a formal account credential.

Protocol 2026-07-28. server/discover, tools/list, ping and list_models are public. Business tools and tasks require a formal bearer and the corresponding REST scope; this example is a public ping.

MCP-Protocol-Version and Mcp-Method must match the body. tools/call also requires Mcp-Name matching params.name; task methods require Mcp-Name matching taskId. Include both _meta keys shown below, even when clientCapabilities is empty. Negotiate Tasks before using task methods.

MCP responses use JSON-RPC, not the REST envelope. Authentication failures return HTTP 401 with WWW-Authenticate; protocol and routing header validation occurs before authentication.

Request parameters

Field	Type	Required	Description
`jsonrpc / id / method`	JSON-RPC	Yes	jsonrpc=2.0, request identifier, matching method.
`params._meta`	object	Yes	io.modelcontextprotocol/protocolVersion and io.modelcontextprotocol/clientCapabilities.

curl --request POST \
  --url 'https://api.perchanceai.art/api/mcp' \
  --header 'X-App-Id: perchanceai' \
  --header 'X-Request-Id: docs-example' \
  --header 'MCP-Protocol-Version: 2026-07-28' \
  --header 'Mcp-Method: ping' \
  --header 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"ping","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}'

Response HTTP 200

Illustrative response shape, not a live API response. Example numbers and USD do not imply fixed pricing or a cash balance. Null fields are omitted.

Field	Type	Required	Description
`jsonrpc / id / result`	JSON-RPC	Yes	Response identifier and result; ping returns resultType=complete.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resultType": "complete"
  }
}

Errors

401 — DEVELOPER_TOKEN_REQUIRED / DEVELOPER_TOKEN_INVALID / DEVELOPER_TOKEN_EXPIRED / DEVELOPER_TOKEN_REVOKED
403 — DEVELOPER_SCOPE_INSUFFICIENT