---
title: "Call an MCP tool over HTTP"
method: POST
path: "/api/v1/mcp"
tags: ["MCP"]
---

# Call an MCP tool over HTTP

`POST /api/v1/mcp`

## Request

- Base URL: `https://aicdapi.com`
- URL: `https://aicdapi.com/api/v1/mcp`
- Auth: HTTP bearer

The Model Context Protocol endpoint. Send a JSON-RPC 2.0 request and receive a JSON-RPC response. Two protocol eras are served: a current-era request carries the protocol version claim in `params._meta` and is answered with a JSON body, while a 2025-era request is answered with the same JSON-RPC payload framed as server-sent events. The available tools, their inputs, their results, and their error codes are published in the `x-aicd-mcp` section of this document. Access requires a customer API key with the MCP scope; a signed-in browser session is not accepted.

## Headers

- `Accept` string
- `MCP-Protocol-Version` string
- `Mcp-Method` string
- `Mcp-Name` string

## Request body

- PostMcpJsonRpcRequest
  - `jsonrpc` '2.0', required
  - `id` union
    - string
    - number
  - `method` string, required
  - `params` object

## Response `200`

The JSON-RPC response. A current-era request receives it as a JSON body; a 2025-era request receives the same payload framed as server-sent events, one `data:` frame per message. A batch array of requests is accepted only on the 2025-era path.

- PostMcpJsonRpcResponse
  - `jsonrpc` '2.0', required
  - `id` union, required
    - string
    - number
  - `result` unknown, required

## Other responses

- `400`: Malformed JSON, an unparsable or negative Content-Length, an unsupported protocol revision, a protocol version that disagrees with the body, or a missing or mismatched Mcp-Method or Mcp-Name header. Answered in the JSON-RPC envelope.
- `401`: The API key is missing, malformed, unknown, revoked, or expired, or the customer is not active. Answered in the REST envelope by the perimeter.
- `403`: The key does not grant the MCP scope, the Origin header does not match the request host, or billing enforcement refused the request. Answered in the REST envelope, except an origin rejection which answers in the JSON-RPC envelope with code -32000.
- `406`: A 2025-era request whose Accept header does not list both `application/json` and `text/event-stream`.
- `413`: The declared or actual request body exceeds 64 KiB.
- `415`: The request Content-Type is not JSON.
- `429`: Either a per-account allowance was exhausted or the account-wide abuse ceiling was reached. The abuse ceiling is account-wide, is not charged against the paid quota, and is charged after the identity lookup and before a revoked, expired, unpaid, or scope-denied rejection is decided.
- `500`: Unexpected failure while handling the request.
- `503`: The identity lookup, audit write, or a rate-limit or abuse-ceiling store failed. The request is refused rather than allowed through. Also: The MCP handler failed. Answered in the REST envelope.

---

[API](https://skmtc.dev/aicdapi/apis/aicd-api.md) · [All operations](https://skmtc.dev/aicdapi/apis/aicd-api/llms.txt) · [OpenAPI document](https://skmtc.dev/aicdapi/apis/aicd-api/revisions/0f3752fae465?raw)