---
title: Overview
description: Connect an AI agent to your Retidal project over the Model Context Protocol.
---

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

<Steps>
<Step title="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`.
</Step>
<Step title="Authenticate">
Every request to `/mcp` carries a Bearer token — see [Authentication](#authentication) below for the two
accepted forms.

```
Authorization: Bearer <token>
```
</Step>
<Step title="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" }
    }
  }
}
```
</Step>
</Steps>

## 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](/mcp/tools)). Create one under [Projects → Scoped API keys](/docs/console/projects#scoped-api-keys). |

<Warning title="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.
</Warning>

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](/docs/console/queries) 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

<Card title="Available tools" href="/mcp/tools">
  The full list of six tools, their arguments, required scopes, and what each one actually does.
</Card>