# MCP Codex Full Reference: The Model Context Protocol (MCP) Manual

## 1. Protocol Architecture & JSON-RPC 2.0 Specification

### 1.1 Lifecycle State Machine
1. **Initialize Request (Client -> Server)**:
   - Method: `initialize`
   - Params: `protocolVersion` (e.g. "2024-11-05"), `capabilities` (roots, sampling, experimental), `clientInfo` ({ name, version }).
2. **Initialize Response (Server -> Client)**:
   - Result: `protocolVersion`, `capabilities` ({ tools, resources, prompts, logging }), `serverInfo` ({ name, version }).
3. **Initialized Notification (Client -> Server)**:
   - Method: `notifications/initialized`
   - Confirms handshake complete. Ready for tool execution and resource subscription.
4. **Normal Operation**:
   - `tools/list`, `tools/call`
   - `resources/list`, `resources/read`, `resources/subscribe`, `notifications/resources/updated`
   - `prompts/list`, `prompts/get`
   - `sampling/createMessage`
   - `ping` -> `{}`
5. **Teardown**:
   - Client closes stdio pipe or terminates SSE session.

### 1.2 Transports
- **STDIO (Standard Input / Output)**:
  - Client spawns server as a subprocess.
  - Client writes newline-delimited JSON-RPC messages to server STDIN.
  - Server writes newline-delimited JSON-RPC messages to STDOUT.
  - CRITICAL RULE: Server MUST NEVER write logs, debug traces, or arbitrary text to STDOUT. All logging must be emitted via STDERR or `notifications/message`.
- **SSE (Server-Sent Events)**:
  - Endpoint GET `/sse`: Server streams events (`event: endpoint`, `event: message`).
  - Endpoint POST `/messages?sessionId=...`: Client sends JSON-RPC payloads to server.
  - Requires keep-alive comments every 15-30s to prevent reverse-proxy timeouts.

---

## 2. Standard MCP JSON-RPC Methods & Schemas

### 2.1 `initialize`
Request:
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "roots": { "listChanged": true },
      "sampling": {}
    },
    "clientInfo": { "name": "AgentHost", "version": "1.0.0" }
  }
}
```
Response:
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": { "listChanged": true },
      "resources": { "subscribe": true, "listChanged": true },
      "prompts": { "listChanged": true }
    },
    "serverInfo": { "name": "mcp-server-example", "version": "1.0.0" }
  }
}
```

### 2.2 `tools/list`
Request:
```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}
```
Response:
```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "query_database",
        "description": "Executes a read-only SQL query against the database.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "query": { "type": "string", "description": "SQL SELECT statement" }
          },
          "required": ["query"]
        }
      }
    ]
  }
}
```

### 2.3 `tools/call`
Request:
```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "query_database",
    "arguments": {
      "query": "SELECT id, name, status FROM deployments WHERE status = 'failed' LIMIT 5;"
    }
  }
}
```
Response:
```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[{\"id\": 101, \"name\": \"auth-service\", \"status\": \"failed\"}]"
      }
    ],
    "isError": false
  }
}
```

### 2.4 `resources/list` & `resources/read`
Request:
```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "resources/read",
  "params": {
    "uri": "postgres://schema/public/tables"
  }
}
```
Response:
```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "contents": [
      {
        "uri": "postgres://schema/public/tables",
        "mimeType": "application/json",
        "text": "{\"tables\": [\"users\", \"orders\", \"deployments\"]}"
      }
    ]
  }
}
```

---

## 3. Curated MCP Server Catalog & Verified Configurations

### 3.1 Developer Tools & VCS
- **GitHub (`@modelcontextprotocol/server-github`)**:
  - Command: `npx -y @modelcontextprotocol/server-github`
  - Env: `GITHUB_PERSONAL_ACCESS_TOKEN`
  - Tools: `create_or_update_file`, `push_files`, `search_repositories`, `create_pull_request`, `list_issues`, `create_issue`
- **Git (`mcp-server-git`)**:
  - Command: `uvx mcp-server-git --repository /path/to/repo`
  - Tools: `git_status`, `git_diff`, `git_log`, `git_commit`
- **Docker (`mcp-server-docker`)**:
  - Command: `npx -y mcp-server-docker`
  - Tools: `list_containers`, `inspect_container`, `container_logs`, `start_container`, `stop_container`
- **Sentry (`mcp-server-sentry`)**:
  - Command: `uvx mcp-server-sentry --auth-token $SENTRY_AUTH_TOKEN`
  - Tools: `list_issues`, `get_issue_details`, `get_event_stacktrace`

### 3.2 Databases & Storage
- **PostgreSQL (`@modelcontextprotocol/server-postgres`)**:
  - Command: `npx -y @modelcontextprotocol/server-postgres postgresql://user:pass@host:5432/db`
  - Tools: `query`, `list_tables`, `describe_table`
- **SQLite (`mcp-server-sqlite`)**:
  - Command: `uvx mcp-server-sqlite --db-path ./data.db`
  - Tools: `read_query`, `write_query`, `create_table`, `list_tables`, `describe_table`
- **MongoDB (`mcp-server-mongodb`)**:
  - Command: `npx -y mcp-server-mongodb mongodb://localhost:27017/db`
  - Tools: `find_documents`, `insert_document`, `aggregate`, `list_collections`
- **ChromaDB (`chroma-mcp`)**:
  - Command: `uvx chroma-mcp --host localhost --port 8000`
  - Tools: `query_collection`, `create_collection`, `add_documents`

### 3.3 Search & Web
- **Brave Search (`@modelcontextprotocol/server-brave-search`)**:
  - Command: `npx -y @modelcontextprotocol/server-brave-search`
  - Env: `BRAVE_API_KEY`
  - Tools: `brave_web_search`, `brave_local_search`
- **Puppeteer (`@modelcontextprotocol/server-puppeteer`)**:
  - Command: `npx -y @modelcontextprotocol/server-puppeteer`
  - Tools: `navigate`, `screenshot`, `click`, `fill`, `evaluate`
- **Fetch (`mcp-server-fetch`)**:
  - Command: `uvx mcp-server-fetch`
  - Tools: `fetch_markdown`

---

## 4. MCP Error Troubleshooting & Remediation Patches

| Error Code | Symptom | Root Cause | Solution Patch |
|---|---|---|---|
| `ENOENT` | `spawn npx ENOENT` | GUI client lacks user `$PATH` | Set `"command"` to absolute path (e.g. `C:/Program Files/nodejs/npx.cmd` or `/usr/local/bin/npx`) |
| `-32603` | `JSON-RPC Internal error` | Server logged to STDOUT | Change `console.log` to `console.error` in server codebase; STDOUT is reserved for JSON-RPC |
| `SSE_CLOSED` | Connection terminated | Proxy buffer timeout | Add `: keep-alive\n\n` ping interval (15s) and `X-Accel-Buffering: no` in reverse proxy |
| `HTTP 403` | GitHub SAML Forbidden | Token lacks SSO authorization | Authorize PAT under GitHub Settings > Personal Access Tokens > Configure SSO |
| `SSL_ERR` | PostgreSQL pg_hba error | Cloud DB enforces SSL | Append `?sslmode=require` to connection URL |
| `EACCES` | Permission denied on file | Filesystem root boundary restriction | Add directory to allowed arguments list in filesystem server configuration |

---

## 5. Agent Instructions & Prompt Injection for MCP
For autonomous AI models interacting with MCP servers:
1. Always call `tools/list` on session initialization to discover dynamically registered capabilities and schemas.
2. Read resource schemas (`resources/read` with `uri=...`) before generating complex SQL or schema-dependent transformations.
3. Handle `-32602` Invalid Params errors by inspecting `inputSchema.required` fields and re-dispatching with valid data types.
4. For long-running operations (>60s), request background job execution or paginate batch queries.