# Connect an Agent to 404.directory

404.directory is a public Streamable HTTP MCP server. Authentication is not
required. To count as one real external Agent, generate one stable random ID
for that Agent installation and send it as `X-404-Agent-ID`. Do not use an
email address, user name, device name, or other personal value. The examples
below already contain a newly generated ID; keep it stable after installing.

MCP endpoint: `https://404.directory/mcp`

## Any stdio MCP client

Use this when a client or Agent directory accepts a command-based MCP server.
The dependency-free bridge creates and preserves one privacy-safe Agent ID
for the installation automatically.

```json
{
  "mcpServers": {
    "404-directory": {
      "command": "npx",
      "args": [
        "-y",
        "@mmvv1638/404-directory-mcp",
        "--source",
        "github.npx"
      ]
    }
  }
}
```

## Codex

Add this to `~/.codex/config.toml`:

```toml
[mcp_servers.404_directory]
url = "https://404.directory/mcp"
http_headers = { "X-404-Agent-ID" = "agent:18945b2a-264c-42ba-8719-faf7c4c71a1f", "X-404-Source" = "github.codex" }
```

## VS Code / GitHub Copilot

[Install in VS Code](https://404.directory/connect/install/vscode?source=github)

## Cursor

[Add 404.directory to Cursor](https://404.directory/connect/install/cursor?source=github)

## Claude Code

```bash
claude mcp add --transport http --scope user 404-directory https://404.directory/mcp \
  --header "X-404-Agent-ID: agent:18945b2a-264c-42ba-8719-faf7c4c71a1f" \
  --header "X-404-Source: github.claude-code"
```

## JavaScript MCP SDK

```ts
const transport = new StreamableHTTPClientTransport(
  new URL("https://404.directory/mcp"),
  {
    requestInit: {
      headers: {
        "X-404-Agent-ID": "agent:18945b2a-264c-42ba-8719-faf7c4c71a1f",
        "X-404-Source": "github.sdk",
      },
    },
  }
)
```

## OpenAI Responses API

Use this JSON as the request body for `POST https://api.openai.com/v1/responses`
with your normal OpenAI API authentication. Replace the question before
sending. The MCP `authorization` value is a random, non-personal
installation token used only for privacy-safe attribution; it does not
grant access. The request limits the MCP surface and forces one real
`search_official_docs` call. OpenAI model usage may incur charges;
404.directory itself currently requires no account or API key.

```json
{
  "model": "gpt-5.6",
  "input": "Use current official sources to answer this real technical question: REPLACE_WITH_YOUR_QUESTION",
  "tools": [
    {
      "type": "mcp",
      "server_label": "directory_404",
      "server_description": "Search current official OpenAI, Microsoft Learn, AWS, and Cloudflare documentation.",
      "server_url": "https://404.directory/mcp",
      "authorization": "agent:18945b2a-264c-42ba-8719-faf7c4c71a1f@github.openai-responses",
      "allowed_tools": [
        "search_official_docs"
      ],
      "require_approval": "never"
    }
  ],
  "tool_choice": {
    "type": "mcp",
    "server_label": "directory_404",
    "name": "search_official_docs"
  }
}
```

## Verify the connection

If the client exposes MCP Prompts, open `research-official-docs`,
`verify-public-deployment`, or `evaluate-agent-tool` and provide one real
task. Opening a prompt is diagnostic only; it must lead to a successful
tool call.

Complete one task the user already needs; never call a tool only to create
traffic. Choose the smallest relevant first call:

- Current AI/cloud documentation: call `search_official_docs` with the
  user's actual technical question and cite the returned first-party URLs.
- A deployment claim: call `verify_web` with the public URL plus an expected
  status or release-specific text.
- Tool selection: call `search_tools`, then inspect the best candidate with
  `get_tool` and `get_trust_score` before recommending it.

The connection is activated only after one non-error tool result. One Agent
counts once toward the public target regardless of later calls.

Progress: https://404.directory/v1/metrics/agents
Reliability: https://404.directory/v1/metrics/reliability?days=30
External Agent pilot: https://github.com/MM-sheng/404-directory/issues/1
Privacy: https://404.directory/privacy