Sign in

Your own agents

Both large model APIs can call a remote MCP server on your behalf. The key travels with your request; Pelyr stores nothing beyond the usage counters it keeps for every key.

Claude API

The MCP connector needs both halves — the server, and a toolset that points at it by name — plus the beta header:

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-client-2025-11-20" \
  -H "content-type: application/json" \
  -d '{
    "model": "<your model>",
    "max_tokens": 4096,
    "mcp_servers": [
      {
        "type": "url",
        "name": "pelyr",
        "url": "https://api.pelyr.com/mcp",
        "authorization_token": "pk_your_key_here"
      }
    ],
    "tools": [{ "type": "mcp_toolset", "mcp_server_name": "pelyr" }],
    "messages": [
      { "role": "user", "content": "Which vessels are in the German Bight right now?" }
    ]
  }'

mcp_servers on its own is rejected as a validation error: the mcp_toolset entry is what makes the tools visible to the model.

Field names and the beta header follow the provider's current documentation; that documentation is the source of truth.

Managed agents

A managed agent declares the server without a token, and the token lives in a vault credential keyed by the server URL:

{
  "display_name": "Pelyr OPEN-AIS",
  "auth": {
    "type": "static_bearer",
    "mcp_server_url": "https://api.pelyr.com/mcp",
    "token": "pk_your_key_here"
  }
}

The agent itself only carries

{
  "mcp_servers": [
    { "type": "url", "name": "pelyr", "url": "https://api.pelyr.com/mcp" }
  ],
  "tools": [{ "type": "mcp_toolset", "mcp_server_name": "pelyr" }]
}

and the session attaches the vault. The key never reaches the agent's sandbox, which matters more here than elsewhere: a sandbox runs code the model wrote.

OpenAI Responses API

The Responses API takes the server as one entry in tools:

{
  "type": "mcp",
  "server_label": "pelyr",
  "server_url": "https://api.pelyr.com/mcp",
  "authorization": "pk_your_key_here",
  "require_approval": "never"
}

require_approval: "never" is defensible here because every Pelyr tool is read-only and none of them spends anything but your own rate limit. Leave approvals on if your own policy says so.

What to expect

  • Tool errors are results, not transport failures. Over the rate limit you get a tool result with error: "rate_limited" and retry_after_seconds, and the connection stays authenticated. Same for a bad bounding box, an unknown MMSI, or a time range that reaches too far back.
  • A revoked key is the exception. It ends the connection: the next tool call returns error: "connection_invalid" or is refused with 401, every request after that gets 401, and the client has to sign in again or be given a new key.
  • An outage answers 503 with a Retry-After header, never 401. That distinction is deliberate — a client must not read an outage as a revoked connection and throw the credential away.
  • Attribution travels in the answer. Every tool result that carries vessel data — find_vessels, get_vessel, get_vessel_track, vessels_at_time, search_vessels, get_detection_overflight, list_sts_finds — carries an attribution block for the licences behind it; list_sources carries the same information per entry in its sources list instead. list_detection_areas and list_detection_overflights carry no AIS vessel facts, so their attribution is empty. Whatever your agent shows or stores has to carry it too.