Connect an agent to Riptide

Start with a working client

Before implementing tool calls, use the discovery client to see the schemas available to your credential. It opens a session and exports the tool catalog without executing tools. Download integration recipes, run its local tests, then supply your gateway URL, tenant ID and API key. The gateway URL is separate from the console and serving hosts. A credential must have the roles for the tools it calls; console-backed tools also require the deployment's console connection to be configured.

1. Authenticate and initialize

Send Authorization: Bearer <api-key> or X-Riptide-Api-Key on every request. Use Content-Type: application/json and Accept: application/json, text/event-stream. Send this body to POST https://<gateway-host>/mcp:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": {
      "name": "my-riptide-client",
      "version": "1.0.0"
    }
  }
}

Save the returned Mcp-Session-Id header. Send it and MCP-Protocol-Version: 2025-06-18 on subsequent requests under the same credential. Send {"jsonrpc":"2.0","method":"notifications/initialized"} next; a notification receives HTTP 202. Sessions expire after 24 hours idle; an unknown or expired session returns 404, so initialize again. DELETE /mcp with the session header closes the session.

2. Discover the schemas

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

Follow result.nextCursor by passing params.cursor until it is absent. Each visible tool carries inputSchema, annotations and metadata for its required role, entitlement, autonomy band, and human approval requirement. Build calls from this catalog; available features depend on the deployment and your credentials.

3. Make a read-only call

Replace the tenant UUID with your own. This call runs under the API-key actor and requires supply.read. Registered-agent calls add the identity and signature described below.

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "riptide.supply.list_publishers",
    "arguments": {
      "tenant_id": "018f0000-0000-7000-8000-000000000001",
      "limit": 10
    }
  }
}

Read the JSON-RPC error field even when HTTP is 200. Successful calls return result.structuredContent and a text rendering in result.content. Mutating tools require arguments.idempotency_key and the fields their schema declares, including a reason where required. Preserve the idempotency key for retries of the same intended change. A response containing awaiting_approval means the change is waiting for a person's approval.

Other transports and MCP methods

REST clients may use GET /v1/tools and POST /v1/tools/invoke with {"tool":"...","tenant_id":"...","input":{}}. A registered identity goes in the top-level agent_id; sign the exact REST body with canonical method POST and path /v1/tools/invoke. Both transports apply the same permissions and approval rules. A customer checkout can run agentgw stdio with RIPTIDE_AGENTGW_STDIO_API_KEY; stdio has no signature header and refuses registered-agent calls, so use HTTP for signed identities.

GET /mcp returns 405: this gateway returns JSON responses and durable tasks, without a server-initiated event stream. OAuth-capable clients can discover /.well-known/oauth-protected-resource when the operator configured an issuer and audience. Unconfigured tools return typed not_wired or dependency errors. Browser sign-in and live-report streams use separate endpoints. See standards and limits for supported AdCP, UCP, and A2A workflows.