import { Code } from '@astrojs/starlight/components';
import { getMarketingApex, LOCAL_PROXY_HTTPS_PORT, settings } from '@rf/config/settings';
import { env } from '../../../lib/docs-env';

export const mcpDocsUrl = (() => {
  // mcp-docs is a region-less, US-primary deployment (settings.yaml
  // `services['mcp-docs']`): it holds no customer data, so one apex
  // deployment serves every developer instead of a per-region cell. Its host
  // follows the same marketing-apex convention as the docs site itself
  // (`getDocsHostname`) and the public status page (`getStatusHostname`):
  // prod -> `<subdomain>.<marketingApex>`, dev/staging ->
  // `<subdomain>-<env>.<nonProdMarketingApex>`, local ->
  // `<subdomain>-local.<nonProdMarketingApex>:<LOCAL_PROXY_HTTPS_PORT>`
  // (Caddy-fronted). Derived from settings so a subdomain rename or apex
  // change flows through without a doc edit.
  const service = settings.services['mcp-docs'];
  if (!service) {
    throw new Error('settings.services["mcp-docs"] is not configured');
  }
  const apex = getMarketingApex(env);
  const suffix = env === 'prod' ? '' : `-${env}`;
  const port = env === 'local' ? `:${LOCAL_PROXY_HTTPS_PORT}` : '';
  return `https://${service.subdomain}${suffix}.${apex}${port}/mcp`;
})();

The docs MCP server gives any MCP-capable AI assistant, for example Claude Code, Claude.ai, ChatGPT, Cursor, or Codex, read-only access to the product documentation and the REST API reference. It is public and unauthenticated: add the URL below and start querying immediately, with no account, no API key, and no login flow.

The server reads two committed, static sources: the documentation guides published on this site and the REST API's OpenAPI document. It holds no database connection, no customer data, and no PII. Every query returns the same public content regardless of who asks.

## Connect your agent

Add the server URL to your AI assistant's MCP configuration or connector settings. No credentials, environment variables, or headers are required.

### Claude Code and Cursor

Add an entry to `.mcp.json` (Claude Code, project-level) or `~/.cursor/mcp.json` (Cursor). Both clients accept the same shape:

<Code
  code={`{
  "mcpServers": {
    "checktiv-docs": { "url": "${mcpDocsUrl}" }
  }
}`}
  lang="json"
/>

### Codex

Add an entry to `~/.codex/config.toml`, or run `codex mcp add` and paste the URL when prompted:

<Code
  code={`[mcp_servers.checktiv-docs]
url = "${mcpDocsUrl}"`}
  lang="toml"
/>

### Claude.ai

1. Open **Customize → Connectors**.
2. Select **Add custom connector**.
3. Paste the server URL, <code>{mcpDocsUrl}</code>, and select **Add**. Leave the OAuth fields blank: the server has no authentication.

On a Team or Enterprise plan, an organization owner adds the connector once under **Organization settings → Connectors** instead (select **Add**, then **Custom**). Members then turn it on from their own **Customize → Connectors**.

### ChatGPT

Developer mode gives ChatGPT full MCP client access, including servers with no authentication. It requires a Plus, Pro, Business, Enterprise, or Education account.

1. Open **Settings → Security and login** and turn on **Developer mode**.
2. Go to **ChatGPT Plugins**, select the plus button, and create a developer-mode app for the docs server. Paste the server URL, <code>{mcpDocsUrl}</code>. The server needs no authentication.
3. Start a conversation, open the composer's plus menu, choose **Developer mode**, and select the app.

## Available tools

- **`list_topics`** - lists the documentation topics `search_docs` and `get_doc` operate over (`guides` and `developers`), each with its slug, label, and a short description. Call this first to discover valid slugs.
- **`search_docs`** - keyword search across the documentation guides and developer reference content, returning matching passages grouped by topic.
- **`get_doc`** - fetches the full text of one documentation topic by its slug (use a slug returned by `list_topics`).
- **`api_reference`** - keyword search over the REST API reference (paths, HTTP methods, summaries, and operation ids), sourced from the same OpenAPI document that powers the [interactive reference](/reference).

Results from `search_docs` and `api_reference` are capped to a small set per query so a response stays a manageable size for a model's context window. Narrow the query, or call `get_doc` directly with a slug from `list_topics`, if you don't find what you need.

## What it does not do

- **No authentication.** There is no account context and no per-caller identity; every caller sees the same public content.
- **No write operations.** All four tools are read-only.
- **No customer data.** The server has no database binding and no secrets. It only reads the committed documentation source and the committed OpenAPI document, so there is nothing to leak.

## Troubleshooting

If a tool call returns no results, confirm the query matches content actually covered in the [Guides](/guides) or [Developers](/developers) sections, or browse the [interactive reference](/reference) directly to find the right term.

A high volume of requests from one IP address is throttled with an HTTP 429 response and a `Retry-After` header. Space out retries; there is no key to rotate and no limit to raise, since the server has no per-caller identity to grant a higher tier to.