# 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",
        "mcp-registry-showcase.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:95edd731-633d-41ef-b10b-7b27d8fd085e", "X-404-Source" = "mcp-registry-showcase.codex" }
```

## VS Code / GitHub Copilot

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

## Cursor

[Add 404.directory to Cursor](https://404.directory/connect/install/cursor?source=mcp-registry-showcase)

## Claude Code

```bash
claude mcp add --transport http --scope user 404-directory https://404.directory/mcp \
  --header "X-404-Agent-ID: agent:95edd731-633d-41ef-b10b-7b27d8fd085e" \
  --header "X-404-Source: mcp-registry-showcase.claude-code"
```

## JavaScript MCP SDK

```ts
const transport = new StreamableHTTPClientTransport(
  new URL("https://404.directory/mcp"),
  {
    requestInit: {
      headers: {
        "X-404-Agent-ID": "agent:95edd731-633d-41ef-b10b-7b27d8fd085e",
        "X-404-Source": "mcp-registry-showcase.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:95edd731-633d-41ef-b10b-7b27d8fd085e@mcp-registry-showcase.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, open `preflight-prediction-market`
with an exact market the user already cares about. Supporting prompts
include `evaluate-agent-tool`, `research-official-docs`, and
`verify-public-deployment`. 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:

- 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.

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
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