MCP server

MCP in one paragraph

The Model Context Protocol (MCP) is an open protocol that lets an AI assistant or agent call tools on a server over JSON-RPC. A client lists the server's tools (tools/list), each with a JSON schema for its arguments, and calls one (tools/call); the result comes back as structured content the assistant can reason over. Coastal Intelligence exposes its agency tools as one MCP server, so an analyst can ask questions in plain language and the assistant fetches scoped, licensed data with its sources attached.

Endpoint and transport

• Endpoint: https://coastal-intelligence.triskelionaisystems.com/api/mcp (this deployment's API origin plus /mcp).
• Transport: MCP streamable HTTP, stateless, JSON responses. Every POST is self-contained; there is no session to keep, so a client can retry freely and a load balancer needs no affinity.
• Server name coastal-intelligence-agency, version 1.0.0. The server's instructions to the assistant: "Coastal Intelligence agency data access. Read-only tools over the shared layers of the bays in your approved access request: bays and the public site register, daily signals, dated bay events, model skill against ground-truth stations, model, satellite and station time series, the bloom back-test and the dataset registry. Every row names its source, product, scale, lead_hours and licence; cite the attribution lines when you publish. Operator records are never available. Every call is logged."
• Read-only: every tool is annotated read-only, non-destructive and idempotent; the server has no resources or prompts.

Authentication

Send the agency key as an HTTP header on every request: Authorization: Bearer <key> (or X-API-Key: <key>). The key is checked before the protocol starts: a missing, unknown or revoked key is answered 401 with WWW-Authenticate: Bearer, and the rate limit (60 calls per minute per key by default, shared with REST) is answered 429 with Retry-After. Both are plain HTTP responses with a JSON detail, not tool errors. See Authentication and keys.

The tools

9 tools, one per shared layer. The table lists every argument; ? marks an optional one. A date is a UTC day as YYYY-MM-DD. Each result is the envelope described on the REST API page, returned as structured content and as JSON text.

Argument naming and dates

• Over MCP the date arguments are from_date and to_date (the REST query names are from and to). The tool schemas say additionalProperties: false: a call with an argument the tool does not declare, such as from, is refused as a tool error instead of quietly using the default window.
• Dates are UTC days, YYYY-MM-DD, inside the key's approved range. Omitted, the window is the last 30 days up to today plus the 10-day forecast horizon; at most 366 days and 20,000 rows per call.

The tool-error shape

A refusal inside the protocol (outside the scope, unknown bay or site, bad argument, too large a window) is not an HTTP error: the call succeeds at the transport level and the result carries isError: true with the reason as a text content block, so the assistant can read it and adjust the call. Shape, with placeholders:

{
  "jsonrpc": "2.0",
  "id": "<request id>",
  "result": {
    "isError": true,
    "content": [
      {
        "type": "text",
        "text": "<the reason, for example: bay '<bay id>' is outside this key's approved scope (...)>"
      }
    ]
  }
}

The reasons are the same texts REST returns in detail for 403, 404 and 422. Only the key check (401) and the rate limit (429) are HTTP responses.

Client configurations

Any client that reads an mcpServers file with type http

Keep the key in an environment variable (AGENCY_KEY), not in the file:

{
  "mcpServers": {
    "coastal-intelligence": {
      "type": "http",
      "url": "https://coastal-intelligence.triskelionaisystems.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${AGENCY_KEY}"
      }
    }
  }
}

Claude Code

Save the file above as .mcp.json in your project, or add the server from the command line:

claude mcp add --transport http coastal-intelligence https://coastal-intelligence.triskelionaisystems.com/api/mcp \
  --header "Authorization: Bearer $AGENCY_KEY"

Claude Desktop and other clients that only start local commands

Bridge to the HTTP endpoint with mcp-remote (needs Node.js):

{
  "mcpServers": {
    "coastal-intelligence": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://coastal-intelligence.triskelionaisystems.com/api/mcp",
        "--header",
        "Authorization:Bearer ${AGENCY_KEY}"
      ],
      "env": {
        "AGENCY_KEY": "<your key>"
      }
    }
  }
}

Checking a configuration

The backend ships a checker, the Python module app.agency.client_check (it needs the official MCP Python SDK). It reads an mcpServers file, expands ${VAR} from the environment, connects with the SDK client, lists the tools and calls one; it prints the tool list and the call's row count and licences, never the key, and exits non-zero on any error:

AGENCY_KEY=<your key> python -m app.agency.client_check \
  --config agency.mcp.json --call get_events \
  --args '{"bay": "<bay id>", "from_date": "<YYYY-MM-DD>", "to_date": "<YYYY-MM-DD>"}'

Without --call it only lists the tools. The type: http configuration above was tested this way against the API.

Three example prompts

Once the server is connected, a user can type requests like these to their assistant:

• "List the bays my key can read, then give me the bay-level bloom signal for <bay> over the last 30 days and tell me which days were at stress or above."
• "Which HAB closures, heatwaves and storm events did <bay> have between <from> and <to>? Give the dates and the source of each, with the attribution lines I must cite."
• "Show the daily risk index for <bay> in <month> as a table per peril, note any suppressed days, and summarise the model skill for sea temperature at the bay's buoy."

Tool descriptions carry the AI disclosure, and every result names its sources and the attribution lines to cite. Signals are favourable, marginal or unfavourable style indicators, not food-safety advice. The REST face of the same tools is at https://coastal-intelligence.triskelionaisystems.com/api/agency/.