# Connect an Agent to 404.directory

404.directory is a public Streamable HTTP MCP server. Authentication is not
required. To become eligible for verified counting, 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.
A successful call is necessary but does not count by itself: the external pilot
must also establish independent-operator evidence through 404.directory.

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

## Enabled service tools

- [`understand_webpage`](https://404.directory/tools/understand_webpage) — inputs and invocation routes.
- [`verify_web`](https://404.directory/tools/verify_web) — inputs and invocation routes.
- [`evaluate_tool_risk`](https://404.directory/tools/evaluate_tool_risk) — inputs and invocation routes.
- [`report_tool_outcome`](https://404.directory/tools/report_tool_outcome) — inputs and invocation routes.
- [`evaluate_prediction_market`](https://404.directory/tools/evaluate_prediction_market) — inputs and invocation routes.
- [`report_prediction_market_outcome`](https://404.directory/tools/report_prediction_market_outcome) — inputs and invocation routes.
- [`search_tools`](https://404.directory/tools/search_tools) — inputs and invocation routes.
- [`get_tool`](https://404.directory/tools/get_tool) — inputs and invocation routes.
- [`compare_tools`](https://404.directory/tools/compare_tools) — inputs and invocation routes.
- [`get_trust_score`](https://404.directory/tools/get_trust_score) — inputs and invocation routes.
- [`recommend_tools`](https://404.directory/tools/recommend_tools) — inputs and invocation routes.
- [`list_capabilities`](https://404.directory/tools/list_capabilities) — inputs and invocation routes.
- [`get_capability_graph`](https://404.directory/tools/get_capability_graph) — inputs and invocation routes.
- [`search_official_docs`](https://404.directory/tools/search_official_docs) — inputs and invocation routes.
- [`inspect_tool_server`](https://404.directory/tools/inspect_tool_server) — inputs and invocation routes.
- [`invoke_registered_tool`](https://404.directory/tools/invoke_registered_tool) — inputs and invocation routes.

## 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",
        "npm.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:bd6d92a0-3d9a-4412-a068-8a8893cca227", "X-404-Source" = "npm.codex" }
```

## VS Code / GitHub Copilot

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

## Cursor

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

## Claude Code

```bash
claude mcp add --transport http --scope user 404-directory https://404.directory/mcp \
  --header "X-404-Agent-ID: agent:bd6d92a0-3d9a-4412-a068-8a8893cca227" \
  --header "X-404-Source: npm.claude-code"
```

## JavaScript MCP SDK

```ts
const transport = new StreamableHTTPClientTransport(
  new URL("https://404.directory/mcp"),
  {
    requestInit: {
      headers: {
        "X-404-Agent-ID": "agent:bd6d92a0-3d9a-4412-a068-8a8893cca227",
        "X-404-Source": "npm.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
`evaluate_prediction_market` call. OpenAI model usage may incur charges;
404.directory itself currently requires no account or API key.

```json
{
  "model": "gpt-5.6",
  "input": "Before I act, preflight this real Polymarket market. Market: REPLACE_WITH_EXACT_POLYMARKET_URL. Intended action: observe. Execution mode: supervised. Geographic eligibility: unknown. Return Decision, Reasons, Evidence, Unknowns, and Next action. Do not predict the winner or trade.",
  "tools": [
    {
      "type": "mcp",
      "server_label": "directory_404",
      "server_description": "Preflight Polymarket and third-party Agent actions with evidence-backed allow, review, or block decisions.",
      "server_url": "https://404.directory/mcp",
      "authorization": "agent:bd6d92a0-3d9a-4412-a068-8a8893cca227@npm.openai-responses",
      "allowed_tools": [
        "evaluate_prediction_market"
      ],
      "require_approval": "never"
    }
  ],
  "tool_choice": {
    "type": "mcp",
    "server_label": "directory_404",
    "name": "evaluate_prediction_market"
  }
}
```

## Verify the connection

If the client exposes MCP Prompts, choose a currently enabled prompt from
`prompts/list`. Opening a prompt is diagnostic only; it must lead to a
successful tool call that answers the user's real task.

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

- Polymarket observation or contemplated Yes/No action: call
  `evaluate_prediction_market` with the exact market, action, approximate
  notional, execution mode, and the geoblock result from the actual
  execution environment. Never treat allow as a forecast or instruction
  to trade; report bounded behavior with `report_prediction_market_outcome`.
- 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.
- Third-party tool installation or first use: call `search_tools` if the
  exact slug is unknown, then call `evaluate_tool_risk` with the intended
  action, data sensitivity, execution mode, and every permission. Obey
  block; pause for human review on review; report the later bounded outcome.

Activation requires a successful business result, not just a non-error
protocol response. Empty searches and connection checks do not activate an
Agent. After independent verification, one Agent installation counts once
toward the public target regardless of later calls.

Verified progress: https://404.directory/v1/metrics/verified-agents
Unverified installation diagnostics: https://404.directory/v1/metrics/agents
Prediction-market preflight: https://404.directory/v1/metrics/prediction-market-evaluations
Risk preflight: https://404.directory/v1/metrics/risk-evaluations
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