MCP

Melious speaks the Model Context Protocol, so an MCP-compatible client — Claude Desktop, a custom agent, anything that talks the protocol — can discover and run our tools without any Melious-specific glue. It's the same tools as the Tools API, reached over MCP instead of plain REST.

Base path: /v1/mcp Auth: Bearer token or x-api-key. Requires scope kit.mcp.

Two transports

• JSON-RPC (POST /v1/mcp/jsonrpc) — the standard MCP transport. This is what MCP clients expect; use it unless you have a reason not to.
• REST (/v1/mcp/initialize, /v1/mcp/tools/list, /v1/mcp/tools/call) — a plain-HTTP convenience surface for hand-rolled clients that don't want to wrap JSON-RPC.

Both expose the same tools and return the same content shapes. The endpoints:

Connect Claude Desktop

Claude Desktop connects to a remote MCP server through the mcp-remote bridge, which handles the transport and forwards your auth header. Add this to your config:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "melious": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://api.melious.ai/v1/mcp/jsonrpc",
        "--header", "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer sk-mel-<YOUR_API_KEY>"
      }
    }
  }
}

No space after the colon in args — Claude Desktop on Windows mangles arguments that contain spaces, so the value with the space lives in env.

Restart Claude Desktop and the Melious tools show up in its tool list. The Claude Desktop guide covers this alongside the larger option — pointing Desktop's own inference at Melious through its third-party gateway mode.

JSON-RPC transport

Standard JSON-RPC 2.0. List the tools:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

Call one:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "web-search",
    "arguments": { "query": "Hanseatic League history" }
  }
}

The result wraps tool output in MCP content blocks:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{ "type": "text", "text": "[{\"title\": \"...\", \"url\": \"...\"}]" }],
    "isError": false
  }
}

A failed call uses the same shape with isError: true and the message as the text block; the HTTP status stays 201.

initialize and ping work as the spec describes. initialize takes protocolVersion, capabilities, and clientInfo, and returns the server's capabilities and serverInfo.

REST transport

If you'd rather not wrap JSON-RPC, the REST endpoints do the same work with the same field names:

curl https://api.melious.ai/v1/mcp/initialize \
  -H "Authorization: Bearer sk-mel-<YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "protocolVersion": "2024-11-05",
    "capabilities": { "tools": {} },
    "clientInfo": { "name": "my-agent", "version": "1.0.0" }
  }'

List and call follow the same pattern. POST /v1/mcp/tools/list (optional {"cursor": "..."} for pagination) returns {"tools": [{"name", "description", "inputSchema"}]}. POST /v1/mcp/tools/call takes {"name", "arguments"} and returns {"content", "isError"}.

curl https://api.melious.ai/v1/mcp/tools/call \
  -H "Authorization: Bearer sk-mel-<YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"name": "web-search", "arguments": {"query": "Hanseatic League history"}}'

Available tools

The same tools as the Tools API — web search, URL scraping, code execution, image generation, and the utility tools. The chat-only tools (search-knowledge, describe-images, transcribe-audio) are listed but return an error result outside a chat. Call tools/list for the live set with current schemas. Document conversion isn't exposed over MCP; it takes file uploads, which the protocol's JSON tool-call shape doesn't carry.

Errors

Three things fail at the HTTP level, with the flat Melious error body {"code", "message", "request_id"}:

Everything else is a protocol-level result, not an HTTP error:

• A tool that doesn't exist, bad arguments, a rate limit, an empty balance, or a tool that fails while running all come back as a normal tools/call result with isError: true and the message in content[0].text. The HTTP status is 201.
• Over JSON-RPC, an unknown method returns {"error": {"code": -32601, "message": "Method not found: …"}}; a failure in initialize, tools/list, or ping returns {"error": {"code": -32000, "message": …}}. There is no data member. A notification (a request without id) gets 202 with an empty body.

Related

Tools API for the same tools over plain REST • Tool calling for letting a chat model drive tools directly.