Overview

Retidal runs an official remote MCP server — a standalone Cloudflare Worker that lets an MCP-capable AI client (Claude Code, Claude Desktop, or any other MCP client) call a fixed set of project-scoped tools directly, instead of you hand-rolling API calls for it.

Connect

1. Get the endpoint

   The server speaks Streamable HTTP MCP at a single URL:

   https://mcp.retidal.com/mcp

   There’s also an unauthenticated liveness check at /healthz.

2. Authenticate

   Every request to /mcp carries a Bearer token — see Authentication below for the two accepted forms.

   Authorization: Bearer <token>

3. Point your client at it

   Any MCP client configured for a remote Streamable HTTP server works. For example, in a client that reads an MCP server list from JSON:

   json

   {
     "mcpServers": {
       "retidal": {
         "url": "https://mcp.retidal.com/mcp",
         "headers": { "Authorization": "Bearer YOUR_API_KEY" }
       }
     }
   }

Authentication

The Authorization header accepts either credential form Retidal already issues, and the server tells them apart by whether a colon is present:

Form	Header value	Resolves to
Project key pair	Bearer <apiKey>:<apiSecret>	ADMIN — every tool is available, scope checks are not consulted.
Scoped API key	Bearer <apiKey> (no colon)	Only the tools whose requiredScope is in that key’s scopes (see Tools). Create one under Projects → Scoped API keys.

A malformed credential is a 401, a resolution failure is a 503

A syntactically bad Authorization header, or a key confirmed not-found/revoked, returns an authentication error. If the credential-resolution dependency itself is unavailable (not the key being wrong), the MCP server returns a service-unavailable error instead — it never reports a platform outage as if it were your invalid credential.

Credential resolution results are cached for 300 seconds (keyed by a hash of the whole Bearer value) so repeated calls in a session don’t re-resolve every time.

What the server can access

The MCP Worker holds no direct database connection — every tool call is forwarded to the same management-API routes documented elsewhere in these docs, over an internal service binding. That means:

• Tool behavior matches the Management API it forwards to, including the same validation and error responses.
• A tool call is recorded to an internal analytics dataset (tool name, project, auth type, success/failure, duration) purely for the platform’s own observability — this does not change what the tool returns to you.

Tool visibility

tools/list only advertises the tools your credential’s scope allows — a scoped key with just mcp:events_read, for example, sees get_integration_guide and list_recent_events and nothing else. All six tools are registered on the server regardless, so a client that calls an unauthorized tool by name directly (bypassing tools/list) still gets a proper scope-denied tool error, not an “unknown tool” error.

Next steps

Available tools

The full list of six tools, their arguments, required scopes, and what each one actually does.