The API as tools for AI agents

Connect Claude Code

claude mcp add --transport http ataila https://portal.example.com/api/v1/mcp --header "Authorization: Bearer <token>"

If the portal's certificate comes from a private certificate authority, Claude Code (a Node program) must trust it, for example with NODE_EXTRA_CA_CERTS=/path/to/ca.pem in its environment.

Any other MCP client

A client that reads the common JSON configuration takes the same three facts: the URL, the transport and the header.

{
  "mcpServers": {
    "ataila": {
      "type": "http",
      "url": "https://portal.example.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

Try it by hand

curl -s https://portal.example.com/api/v1/mcp \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"whoami_get","arguments":{}}}'

The endpoint

Authentication

The same bearer credential as every other /api/v1 operation: Authorization: Bearer <token>, with a personal token (ataila_pat_…) or a service-account token (ataila_sat_…); as on every operation, a portal session JWT is accepted as well. A missing or invalid credential is an HTTP 401 problem document, not a JSON-RPC error. A token's IP allowlist, when one is set, applies to the tool calls too. It is compared with the client address as the installation records it, which is the real client only where the installation's entry point passes that address on; where it does not, a token allowlisted to a client's address is refused: the allowlist fails closed. A revoked token stops at once on the API worker that revoked it and wherever the shared cache answers; while the shared cache is unreachable, another worker may accept it for up to 30 seconds more.

Tools

• One tool per read operation of /api/v1, generated from the API's own routes and contract. The name is the operation id, the title its summary, the description its summary and description.
• Arguments are the operation's path parameters (required) and query parameters (required only when the operation requires them). Unknown or missing arguments are JSON-RPC error -32602, and nothing is sent. A path argument must be a single path segment.
• tools/list shows only what the caller may call with its effective permissions. The operations still enforce them: calling an unlisted tool returns the operation's own 403 as a tool error.
• Results are one text item holding the API's JSON answer, plus structuredContent with the same JSON. An error answer is isError: true with the problem document as the text.
• Lists are paged: pass a page's next_cursor as cursor to get the next.
• The licence bundle is always null over MCP. Tool results land in a model's context, and the bundle is the one read whose value is itself a credential. Every member the contract marks SENSITIVE is nulled, and the tool's description says so. A result that carried a non-null secret would be withheld as an error.

In API 1.0.0 (platform release 1.0.187) there are 47 tools. Each links to its operation in the reference: