Terminal49 · dodeja · Jul 22, 2026 · Jul 22, 2026 · Jul 22, 2026 · Jul 22, 2026
diff --git a/docs/api-docs/in-depth-guides/mcp.mdx b/docs/api-docs/in-depth-guides/mcp.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Terminal49 MCP Server Quickstart"
-description: "Set up the Terminal49 MCP server in Claude Desktop, Cursor, or another MCP-compatible client to query live shipment and container tracking data."
+description: "Set up the Terminal49 MCP server in Claude, ChatGPT, Cursor, Microsoft Copilot, or another MCP-compatible client to query live shipment and container tracking data."
 keywords:
   - "Terminal49 MCP server"
   - "AI container tracking"
@@ -10,10 +10,10 @@ keywords:
   - "Cursor"
   - "MCP config"
 ---
-This guide covers everything you need to connect Claude or Cursor to Terminal49's container tracking data via MCP.
+This guide covers everything you need to connect an MCP client to Terminal49's container tracking data.
 
 <Note>
-Just want to get started fast? See [MCP Overview](/mcp/home) for a 5-minute setup.
+Just want to get started fast? See the per-tool setup guides for [Claude](/mcp/setup/claude), [Claude Code](/mcp/setup/claude-code), [ChatGPT](/mcp/setup/chatgpt), [Cursor](/mcp/setup/cursor), [Microsoft Copilot](/mcp/setup/microsoft-copilot), and [VS Code](/mcp/setup/vs-code), or the [MCP Overview](/mcp/home) for a 5-minute setup.
 </Note>
 
 ## Prerequisites
@@ -22,16 +22,16 @@ Before you begin, make sure you have:
 
 <CardGroup cols={2}>
   <Card title="Terminal49 account" icon="user">
-    A Terminal49 account with API access
+    You sign in with your Terminal49 credentials during the OAuth flow — no API key needed
   </Card>
-  <Card title="API key" icon="key">
-    An API key from the [developer portal](https://app.terminal49.com/developers/api-keys)
+  <Card title="API key (optional)" icon="key">
+    Only needed for clients without OAuth support or the local stdio server — create one in the [developer portal](https://app.terminal49.com/developers/api-keys)
   </Card>
   <Card title="Node.js 24.x" icon="node-js">
     Required if running the MCP server locally
   </Card>
   <Card title="MCP client" icon="robot">
-    Claude Desktop or Cursor IDE
+    Claude, ChatGPT, Cursor, Microsoft Copilot, VS Code, or any MCP-compatible client
   </Card>
 </CardGroup>
 
@@ -49,17 +49,17 @@ Before you begin, make sure you have:
 |-----------|----------|----------|
 | HTTP (streamable) | `POST https://mcp.terminal49.com` | Serverless, short-lived requests |
 
-**Authentication**: API key only (OAuth not required for this release).
-Pass `Authorization: Token YOUR_API_KEY`. Use the `Token` scheme for API keys. The `Bearer` scheme is reserved for WorkOS OAuth access tokens — it currently accepts API keys for backward compatibility, but once OAuth is enabled, `Bearer` accepts only WorkOS tokens.
+**Authentication**: OAuth 2.1 (recommended) or API key.
 
-The hosted endpoint always requires the `Authorization` header. Only the [local stdio server](#local-stdio-development) reads the `T49_API_TOKEN` environment variable instead of a header.
+- **OAuth 2.1** – no API key needed. Add `https://mcp.terminal49.com` to your client; it discovers the authorization server (`https://auth.terminal49.com`) via protected resource metadata, registers itself with Dynamic Client Registration, and opens your browser so you can sign in with your Terminal49 credentials. Tokens are stored and refreshed by the client.
+- **API key** – for clients that can't run a browser OAuth flow, pass `Authorization: Token YOUR_API_KEY`. Use the `Token` scheme for API keys; the `Bearer` scheme is used for OAuth access tokens, which OAuth clients obtain automatically.
+
+Only the [local stdio server](#local-stdio-development) reads the `T49_API_TOKEN` environment variable instead of a header.
 
 <Tip>
-Claude Desktop and Cursor use the HTTP transport. For hosted production usage, connect to `https://mcp.terminal49.com` — the root origin is the canonical connector URL.
+For hosted production usage, connect to `https://mcp.terminal49.com` — the root origin is the canonical connector URL and OAuth resource identifier.
 </Tip>
 
-{/* OAuth hosted docs are not yet published. Links will be added when the pages are available. */}
-
 ---
 
 ## Observability
@@ -82,72 +82,36 @@ SENTRY_SEND_DEFAULT_PII=false
 
 ## Configure your MCP client
 
-### Claude Desktop
-
-<Tabs>
-  <Tab title="macOS">
-    Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
-
-    ```json
-    {
-      "mcpServers": {
-        "terminal49": {
-          "url": "https://mcp.terminal49.com",
-          "headers": {
-            "Authorization": "Token YOUR_API_KEY"
-          }
-        }
-      }
-    }
-    ```
-  </Tab>
-  <Tab title="Windows">
-    Edit `%APPDATA%\Claude\claude_desktop_config.json`:
-
-    ```json
-    {
-      "mcpServers": {
-        "terminal49": {
-          "url": "https://mcp.terminal49.com",
-          "headers": {
-            "Authorization": "Token YOUR_API_KEY"
-          }
-        }
-      }
-    }
-    ```
-  </Tab>
-  <Tab title="Linux">
-    Edit `~/.config/Claude/claude_desktop_config.json`:
-
-    ```json
-    {
-      "mcpServers": {
-        "terminal49": {
-          "url": "https://mcp.terminal49.com",
-          "headers": {
-            "Authorization": "Token YOUR_API_KEY"
-          }
-        }
-      }
-    }
-    ```
-  </Tab>
-</Tabs>
+### OAuth setup (recommended)
 
-### Cursor IDE
+Most clients connect with just the server URL and a browser sign-in — no API key. Follow the guide for your tool:
 
-Add to your Cursor settings:
+- [Claude](/mcp/setup/claude) – claude.ai and Claude Desktop
+- [Claude Code](/mcp/setup/claude-code) – one `claude mcp add` command
+- [ChatGPT](/mcp/setup/chatgpt) – custom connector with Developer mode
+- [Cursor](/mcp/setup/cursor) – `mcp.json` or Cursor Settings → MCP
+- [Microsoft Copilot](/mcp/setup/microsoft-copilot) – Copilot Studio agent tools
+- [VS Code](/mcp/setup/vs-code) – GitHub Copilot agent mode
+- [Agent plugins](/mcp/setup/agent-plugins) – Terminal49 plugin for Claude Code, Cursor, Codex, and GitHub Copilot CLI
+- [Other MCP clients](/mcp/setup/other-clients) – generic configuration
+
+The manual configurations below use an API key instead. Use them for clients or environments where the browser OAuth flow isn't practical.
+
+<Warning>
+claude.ai and Claude Desktop cannot send a static API-key header — they always authenticate through the OAuth connector flow. Follow the [Claude setup guide](/mcp/setup/claude) to connect them. For API-key-based local development in Claude Desktop, use the [local stdio server](#local-stdio-development) below instead.
+</Warning>
+
+### Cursor IDE (manual, API key)
+
+Add to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for all projects):
 
 ```json
 {
-  "mcp": {
-    "servers": {
-      "terminal49": {
-        "url": "https://mcp.terminal49.com",
-        "headers": {
-          "Authorization": "Token YOUR_API_KEY"
-        }
+  "mcpServers": {
+    "terminal49": {
+      "url": "https://mcp.terminal49.com",
+      "headers": {
+        "Authorization": "Token YOUR_API_KEY"
       }
     }
   }
@@ -229,7 +193,7 @@ Need test container numbers? See [Test Numbers](/api-docs/useful-info/test-numbe
 | Symptom | Likely Cause | How to Fix |
 |---------|--------------|------------|
 | "Cannot connect to MCP server" | Wrong URL or config path | Confirm URL is `https://mcp.terminal49.com` and config file path matches your OS |
-| `401 Unauthorized` | Missing or invalid API key | Create a new API key in the [developer portal](https://app.terminal49.com/developers/api-keys); ensure the `Authorization: Token YOUR_API_KEY` header is set |
+| `401 Unauthorized` | Expired OAuth session, or missing/invalid API key | Disconnect and reconnect the connector to re-run the OAuth sign-in. If using an API key, create a new one in the [developer portal](https://app.terminal49.com/developers/api-keys) and ensure the `Authorization: Token YOUR_API_KEY` header is set |
 | `429 Too Many Requests` | Rate limit exceeded | See [Rate Limiting](/api-docs/in-depth-guides/rate-limiting); use webhooks instead of polling |
 | Tools list is empty | Config not loaded | Restart Claude/Cursor; check MCP inspector for errors |
 | "Tool not found" | Typo in tool name | Use exact names: `search_container`, `get_container`, etc. |
@@ -406,6 +370,8 @@ echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"search_container"
 curl -X POST https://mcp.terminal49.com \
   -H "Authorization: Token $T49_API_TOKEN" \
   -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "MCP-Protocol-Version: 2025-06-18" \
   -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
 ```
 
@@ -414,6 +380,7 @@ curl -X POST https://mcp.terminal49.com \
 ## Related guides
 
 - [MCP Overview](/mcp/home) – Quick start and tools reference
+- Setup guides: [Claude](/mcp/setup/claude), [Claude Code](/mcp/setup/claude-code), [ChatGPT](/mcp/setup/chatgpt), [Cursor](/mcp/setup/cursor), [Microsoft Copilot](/mcp/setup/microsoft-copilot), [VS Code](/mcp/setup/vs-code), [Agent plugins](/mcp/setup/agent-plugins), [Other clients](/mcp/setup/other-clients)
 - [Rate Limiting](/api-docs/in-depth-guides/rate-limiting) – API limits (same for MCP)
 - [Test Numbers](/api-docs/useful-info/test-numbers) – Containers for testing
 - [Webhooks](/api-docs/in-depth-guides/webhooks) – Real-time updates

diff --git a/docs/docs.json b/docs/docs.json
@@ -417,6 +417,19 @@
               "mcp/home",
               "api-docs/in-depth-guides/mcp"
             ]
+          },
+          {
+            "group": "Setup Guides",
+            "pages": [
+              "mcp/setup/claude",
+              "mcp/setup/claude-code",
+              "mcp/setup/chatgpt",
+              "mcp/setup/cursor",
+              "mcp/setup/microsoft-copilot",
+              "mcp/setup/vs-code",
+              "mcp/setup/agent-plugins",
+              "mcp/setup/other-clients"
+            ]
           }
         ]
       },

diff --git a/docs/mcp/home.mdx b/docs/mcp/home.mdx
@@ -1,72 +1,46 @@
 ---
 title: "Terminal49 MCP Server"
 sidebarTitle: "MCP Overview"
-description: "Connect the Terminal49 MCP server to Claude Desktop or Cursor so AI tools can query, search, and answer questions with live shipment tracking data."
+description: "Connect the Terminal49 MCP server to Claude, ChatGPT, Cursor, Microsoft Copilot, or any MCP client so AI tools can query, search, and answer questions with live shipment tracking data."
 keywords:
   - "Terminal49 MCP server"
   - "AI container tracking"
   - "live shipment data"
-  - "Claude Desktop"
+  - "Claude"
+  - "ChatGPT"
   - "Cursor"
+  - "Microsoft Copilot"
+  - "OAuth"
   - "MCP config"
   - "shipment data assistant"
 ---
-Use the Terminal49 MCP server to let Claude or Cursor answer questions with live container and shipment data—without writing custom glue code.
+Use the Terminal49 MCP server to let Claude, ChatGPT, Cursor, Microsoft Copilot, or any MCP client answer questions with live container and shipment data—without writing custom glue code.
 
 ## TL;DR – get started in 5 minutes
 
 <Steps>
-  <Step title="Get your API key">
-    Create an API key in the [developer portal](https://app.terminal49.com/developers/api-keys).
-  </Step>
   <Step title="Pick your MCP client">
-    - **Claude Desktop** (macOS / Windows / Linux)
-    - **Cursor IDE**
+    Follow the setup guide for your tool:
+
+    - [Claude](/mcp/setup/claude) (claude.ai, Claude Desktop)
+    - [Claude Code](/mcp/setup/claude-code)
+    - [ChatGPT](/mcp/setup/chatgpt)
+    - [Cursor](/mcp/setup/cursor)
+    - [Microsoft Copilot](/mcp/setup/microsoft-copilot) (Copilot Studio)
+    - [VS Code](/mcp/setup/vs-code) (GitHub Copilot)
+    - [Agent plugins](/mcp/setup/agent-plugins) (Claude Code, Cursor, Codex, GitHub Copilot CLI)
+    - [Other MCP clients](/mcp/setup/other-clients)
   </Step>
-  <Step title="Paste this config (Claude Desktop)">
-    Edit the Claude Desktop config file for your operating system:
-
-    | OS | Config path |
-    | --- | --- |
-    | macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
-    | Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
-    | Linux | `~/.config/Claude/claude_desktop_config.json` |
-
-    ```json
-    {
-      "mcpServers": {
-        "terminal49": {
-          "url": "https://mcp.terminal49.com",
-          "headers": {
-            "Authorization": "Token YOUR_API_KEY"
-          }
-        }
-      }
-    }
-    ```
-
-    <Accordion title="Cursor IDE config">
-    ```json
-    {
-      "mcp": {
-        "servers": {
-          "terminal49": {
-            "url": "https://mcp.terminal49.com",
-            "headers": {
-              "Authorization": "Token YOUR_API_KEY"
-            }
-          }
-        }
-      }
-    }
-    ```
-    </Accordion>
+  <Step title="Add the connector URL">
+    Point the client at `https://mcp.terminal49.com`. No API key needed.
+  </Step>
+  <Step title="Sign in to Terminal49">
+    The server supports OAuth 2.1: your client opens a browser window, you sign in with your Terminal49 credentials and approve access. That's it.
   </Step>
-  <Step title="Ask Claude">
-    > "Using the Terminal49 MCP server, track container CAIU1234567 with Maersk."
+  <Step title="Ask a question">
+    > "Using the Terminal49 MCP server, search for container CAIU1234567 and summarize its status."
   </Step>
   <Step title="Explore tools">
-    Ask Claude:
     > "List the tools available in the Terminal49 MCP server and what they're for."
   </Step>
 </Steps>
@@ -86,17 +60,54 @@ For the full walkthrough (including local stdio dev, deployment, and SDK example
 | HTTP (streamable) | `POST https://mcp.terminal49.com` | Serverless, short-lived requests |
 
 **Authentication**:
-- API key only (OAuth not required for this release)
-- Pass `Authorization: Token YOUR_API_KEY`. Use the `Token` scheme for API keys. The `Bearer` scheme is reserved for WorkOS OAuth access tokens — it currently accepts API keys for backward compatibility, but once OAuth is enabled, `Bearer` accepts only WorkOS tokens.
-- The hosted endpoint always requires the `Authorization` header. Only the [local stdio server](/api-docs/in-depth-guides/mcp#local-stdio-development) reads the `T49_API_TOKEN` environment variable instead of a header.
+- **OAuth 2.1 (recommended)** – no API key needed. Add the connector URL, sign in with your Terminal49 credentials in the browser window your client opens, and approve access. Clients discover the authorization server (`https://auth.terminal49.com`) automatically and use authorization code with PKCE and Dynamic Client Registration.
+- **API key (for clients without OAuth support)** – create a key in the [developer portal](https://app.terminal49.com/developers/api-keys) and pass `Authorization: Token YOUR_API_KEY`. Use the `Token` scheme for API keys; the `Bearer` scheme is used for OAuth access tokens, which OAuth clients obtain automatically.
+- The [local stdio server](/api-docs/in-depth-guides/mcp#local-stdio-development) reads the `T49_API_TOKEN` environment variable instead.
 
 <Tip>
 Connector URL: `https://mcp.terminal49.com`. It is the canonical OAuth resource identifier, so OAuth clients (ChatGPT, Claude connectors) bind to the correct token audience.
 </Tip>
 
+## Setup guides
+
+<CardGroup cols={3}>
+  <Card title="Claude" href="/mcp/setup/claude">
+    claude.ai and Claude Desktop connectors
+  </Card>
+  <Card title="Claude Code" href="/mcp/setup/claude-code">
+    One `claude mcp add` command from your terminal
+  </Card>
+  <Card title="ChatGPT" href="/mcp/setup/chatgpt">
+    Custom connector with Developer mode
+  </Card>
+  <Card title="Cursor" href="/mcp/setup/cursor">
+    `mcp.json` or Cursor Settings → MCP
+  </Card>
+  <Card title="Microsoft Copilot" href="/mcp/setup/microsoft-copilot">
+    Copilot Studio agent tools
+  </Card>
+  <Card title="VS Code" href="/mcp/setup/vs-code">
+    GitHub Copilot agent mode
+  </Card>
+  <Card title="Agent plugins" href="/mcp/setup/agent-plugins">
+    Terminal49 plugin for Claude Code, Cursor, Codex, and Copilot CLI
+  </Card>
+  <Card title="Other MCP clients" href="/mcp/setup/other-clients">
+    Generic OAuth or API-key configuration
+  </Card>
+</CardGroup>
+
 ## Any MCP client
 
-Use the same hosted Streamable HTTP endpoint in any MCP-compatible client:
+Use the same hosted Streamable HTTP endpoint in any MCP-compatible client. With an OAuth-capable client, no credentials are needed — just the URL:
+
+```json
+{
+  "url": "https://mcp.terminal49.com"
+}
+```
+
+If your client can't run a browser OAuth flow, pass an API key instead:
 
 ```json
 {
@@ -107,9 +118,7 @@ Use the same hosted Streamable HTTP endpoint in any MCP-compatible client:
 }
 ```
 
-<Note>
-OAuth is not available for the hosted MCP server yet. Use a Terminal49 API key until OAuth support is published.
-</Note>
+See [Other MCP clients](/mcp/setup/other-clients) for details on OAuth discovery and verification.
 
 The same [rate limits](/api-docs/in-depth-guides/rate-limiting) apply to MCP endpoints as the REST API.