MCP integration

Turn any API into an MCP-ready tool

ToolRelay's MCP mode exposes every tool you create as an MCP-compatible JSON endpoint. AI agents can discover the schema, call the tool with structured arguments, and receive a wrapped response — with auth, plan limits, and usage logging handled for you.

Create your first MCP tool Open the dashboard

How a ToolRelay tool maps to MCP

The tool slug becomes the MCP tool name.
The description, input_schema, and output_example you provide are returned by the metadata endpoint so agents can present and validate inputs.
POST calls accept { "arguments": { ... } }; ToolRelay forwards the arguments to your upstream URL and wraps the response.
Public tools are open. Private tools require an x-toolrelay-key header.

Endpoint URLs

Each tool you create exposes both an MCP endpoint and a raw HTTP proxy. They share the same auth, plan limits, and usage log writes — they only differ in response shape.

MCP endpoint

Raw HTTP proxy

GET — tool metadata

GET /api/mcp/[slug] returns the tool's discovery payload. Agents can use this to populate their tool registry.

{
  "name": "private-pro-test",
  "description": "Example ToolRelay tool",
  "input_schema": { ... },
  "output_example": { ... },
  "method": "POST",
  "endpoint": "https://www.toolrelay.online/api/mcp/private-pro-test",
  "run_endpoint": "https://www.toolrelay.online/api/run/private-pro-test",
  "security": "x-toolrelay-key required"
}

POST — call the tool

POST /api/mcp/[slug] accepts a JSON body with an arguments object. ToolRelay forwards the arguments to your upstream endpoint and returns the response wrapped in MCP-style content.

Private tool example

curl -i -X POST "https://www.toolrelay.online/api/mcp/private-pro-test" \
  -H "Content-Type: application/json" \
  -H "x-toolrelay-key: trk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{"arguments":{"message":"hello from an agent"}}'

Public tool example

curl -i -X POST "https://www.toolrelay.online/api/mcp/your-public-slug" \
  -H "Content-Type: application/json" \
  -d '{"arguments":{"message":"hello"}}'

Wrapped response

{
  "content": [
    { "type": "text", "text": "{\"echoed\":\"hello from an agent\"}" }
  ],
  "upstream_status": 200
}

JSON config example

Drop this into an MCP client / agent config to register the tool by URL.

{
  "name": "private-pro-test",
  "description": "Example ToolRelay tool",
  "endpoint": "https://www.toolrelay.online/api/mcp/private-pro-test",
  "method": "POST",
  "security": "x-toolrelay-key required",
  "headers": {
    "x-toolrelay-key": "trk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  "input_schema": {
    "type": "object",
    "properties": {
      "message": {
        "type": "string"
      }
    },
    "required": [
      "message"
    ]
  }
}

Security notes

Private MCP tools require a per-tool API key (trk_…) sent as x-toolrelay-key. Missing → 401 unauthorized_missing_key; wrong → 401 unauthorized_invalid_key.
Public MCP tools ignore the header and accept anonymous traffic.
The full trk_ key is shown exactly once on creation and on regeneration. Only the prefix and SHA-256 hash are persisted.
The upstream endpoint_url and any custom auth-header value are never echoed by the metadata endpoint — agents only see the ToolRelay-facing surface.
SSRF guard rejects localhost / private IP ranges. Every upstream call has a 25s timeout. All calls are written to usage_logs.

Known limitation

This is an MCP-ready JSON interface MVP. Full MCP protocol transports (SSE / stdio) and capability negotiation will land in a follow-up. Agents that can call HTTP JSON endpoints with custom headers can use ToolRelay tools today.

Create your first MCP tool