diff --git a/docs/api-docs/in-depth-guides/mcp.mdx b/docs/api-docs/in-depth-guides/mcp.mdx index d4be0832..ed0cae67 100644 --- 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. -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. ## Prerequisites @@ -22,16 +22,16 @@ Before you begin, make sure you have: - A Terminal49 account with API access + You sign in with your Terminal49 credentials during the OAuth flow — no API key needed - - An API key from the [developer portal](https://app.terminal49.com/developers/api-keys) + + 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) Required if running the MCP server locally - Claude Desktop or Cursor IDE + Claude, ChatGPT, Cursor, Microsoft Copilot, VS Code, or any MCP-compatible client @@ -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. -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. -{/* 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 - - - - Edit `~/Library/Application Support/Claude/claude_desktop_config.json`: - - ```json - { - "mcpServers": { - "terminal49": { - "url": "https://mcp.terminal49.com", - "headers": { - "Authorization": "Token YOUR_API_KEY" - } - } - } - } - ``` - - - Edit `%APPDATA%\Claude\claude_desktop_config.json`: - - ```json - { - "mcpServers": { - "terminal49": { - "url": "https://mcp.terminal49.com", - "headers": { - "Authorization": "Token YOUR_API_KEY" - } - } - } - } - ``` - - - Edit `~/.config/Claude/claude_desktop_config.json`: - - ```json - { - "mcpServers": { - "terminal49": { - "url": "https://mcp.terminal49.com", - "headers": { - "Authorization": "Token YOUR_API_KEY" - } - } - } - } - ``` - - +### 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. + + +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. + + +### 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 index b99b1c80..8f15c622 100644 --- 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 index 28985455..d479039c 100644 --- 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 - - Create an API key in the [developer portal](https://app.terminal49.com/developers/api-keys). - - - **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) - - 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" - } - } - } - } - ``` - - - ```json - { - "mcp": { - "servers": { - "terminal49": { - "url": "https://mcp.terminal49.com", - "headers": { - "Authorization": "Token YOUR_API_KEY" - } - } - } - } - } - ``` - + + Point the client at `https://mcp.terminal49.com`. No API key needed. + + + 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. - - > "Using the Terminal49 MCP server, track container CAIU1234567 with Maersk." + + > "Using the Terminal49 MCP server, search for container CAIU1234567 and summarize its status." - Ask Claude: > "List the tools available in the Terminal49 MCP server and what they're for." @@ -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. 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. +## Setup guides + + + + claude.ai and Claude Desktop connectors + + + One `claude mcp add` command from your terminal + + + Custom connector with Developer mode + + + `mcp.json` or Cursor Settings → MCP + + + Copilot Studio agent tools + + + GitHub Copilot agent mode + + + Terminal49 plugin for Claude Code, Cursor, Codex, and Copilot CLI + + + Generic OAuth or API-key configuration + + + ## 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: } ``` - -OAuth is not available for the hosted MCP server yet. Use a Terminal49 API key until OAuth support is published. - +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. diff --git a/docs/mcp/setup/agent-plugins.mdx b/docs/mcp/setup/agent-plugins.mdx new file mode 100644 index 00000000..3717a218 --- /dev/null +++ b/docs/mcp/setup/agent-plugins.mdx @@ -0,0 +1,96 @@ +--- +title: "Install the Terminal49 Agent Plugin" +sidebarTitle: "Agent plugins" +description: "Install the Terminal49 plugin in Claude Code, Cursor, Codex, or GitHub Copilot CLI — MCP connection plus a container-tracking skill, with OAuth and no API key." +keywords: + - "Terminal49 agent plugins" + - "Terminal49 plugin" + - "container-tracking skill" + - "Claude Code plugin" + - "Cursor plugin" + - "Codex plugin" + - "GitHub Copilot CLI plugin" + - "OAuth" + - "container tracking" +--- +Install the **Terminal49** plugin from the [Terminal49/agent-plugins](https://github.com/Terminal49/agent-plugins) marketplace to set up your coding agent in one step. The plugin configures the Terminal49 MCP server connection (`https://mcp.terminal49.com`) and adds a shared `container-tracking` skill, so you don't have to add the server manually. + + +**No API key required.** The plugin contains no API keys or customer data. Authentication uses the same OAuth 2.1 browser flow as a direct MCP connection — sign in with your Terminal49 credentials when your agent first connects. + + +## What the plugin provides + +- OAuth connection to `https://mcp.terminal49.com` — the same hosted MCP server the [other setup guides](/mcp/home#setup-guides) configure directly +- A shared `container-tracking` skill that teaches agents how to choose and sequence the Terminal49 tools when searching, tracking, and investigating container shipments +- Workflow guidance for status, pickup readiness, holds, ETAs, routes, delays, and demurrage-risk questions +- Guardrails around tracking-request creation, credentials, dates, and missing data + +## Install + + + + ```sh + claude plugin marketplace add Terminal49/agent-plugins + claude plugin install terminal49@terminal49 + ``` + + The first time the Terminal49 tools are used, sign in through the browser OAuth flow. If you aren't prompted, run `/mcp`, select **terminal49**, and choose **Authenticate**. + + Prefer adding the MCP server directly? See the [Claude Code guide](/mcp/setup/claude-code). + + + In Cursor chat, run: + + ```text + /add-plugin https://github.com/Terminal49/agent-plugins + ``` + + Then select and install **Terminal49**. Cursor prompts you to connect the MCP server (the browser OAuth sign-in) when the plugin first needs it. + + Prefer adding the MCP server directly? See the [Cursor guide](/mcp/setup/cursor). + + + ```sh + codex plugin marketplace add Terminal49/agent-plugins + codex plugin add terminal49@terminal49 + ``` + + + Copilot CLI reads the Claude-compatible marketplace included in the repository: + + ```sh + copilot plugin marketplace add Terminal49/agent-plugins + copilot plugin install terminal49@terminal49 + ``` + + + +## Test the plugin + +After connecting your Terminal49 account, ask your agent: + +> "Where is container CAIU1234567?" + +> "Is this container ready for pickup, and are there any holds?" + +It should use tools such as `search_container`, `track_container`, and `get_container`. See the [tools reference](/mcp/home#tools-reference) for the full list, and [Test Numbers](/api-docs/useful-info/test-numbers) for containers you can use during development. + +## Troubleshooting + +| Symptom | How to fix | +|---------|------------| +| Marketplace add fails | Confirm the marketplace reference is exactly `Terminal49/agent-plugins` (in Cursor, the full URL `https://github.com/Terminal49/agent-plugins`) | +| Plugin installed but tools missing | Restart the agent session so it reloads the plugin's MCP configuration | +| Sign-in window never opens | Pop-up blocked or no default browser — allow pop-ups and retry the authenticate action (in Claude Code, run `/mcp` and choose **Authenticate**) | +| `401 Unauthorized` after connecting | Re-authenticate from your client's MCP settings to refresh the OAuth token | + +For plugin sources, the shared skill, and contribution guidelines, see the [repository README](https://github.com/Terminal49/agent-plugins#readme). + +## Related guides + +- [Claude Code](/mcp/setup/claude-code) – Add the MCP server directly with `claude mcp add` +- [Cursor](/mcp/setup/cursor) – Add the MCP server directly via `mcp.json` +- [MCP Overview](/mcp/home) – Tools, prompts, and resources reference +- [MCP Server Quickstart](/api-docs/in-depth-guides/mcp) – Full setup, including API-key and local stdio options +- [Other MCP clients](/mcp/setup/other-clients) – Generic configuration for any client diff --git a/docs/mcp/setup/chatgpt.mdx b/docs/mcp/setup/chatgpt.mdx new file mode 100644 index 00000000..edf1b966 --- /dev/null +++ b/docs/mcp/setup/chatgpt.mdx @@ -0,0 +1,74 @@ +--- +title: "Connect ChatGPT to Terminal49" +sidebarTitle: "ChatGPT" +description: "Connect ChatGPT to the Terminal49 MCP server as a custom connector with OAuth — no API key required." +keywords: + - "Terminal49 MCP server" + - "ChatGPT connector" + - "ChatGPT MCP" + - "developer mode" + - "OAuth" + - "container tracking" +--- +Connect ChatGPT to the Terminal49 MCP server so it can answer questions with live container and shipment tracking data. + + +**No API key required.** The Terminal49 MCP server supports OAuth 2.1. When you connect, ChatGPT opens a browser sign-in page — log in with your Terminal49 credentials and you're done. + + +## Prerequisites + +- A paid ChatGPT plan. Custom MCP connectors require **Developer mode**, available on Plus, Pro, Business, Enterprise, and Edu plans. Free accounts cannot add custom connectors. +- On Business, Enterprise, and Edu workspaces, an admin may need to enable Developer mode or approve the connector for the workspace. + +## Add the connector + + + + In ChatGPT, open **Settings**, find the connectors section (labeled **Connectors** or **Apps**, depending on your version), open **Advanced settings**, and turn on **Developer mode**. + + + In the same connectors section, click **Create** (or **Add custom connector**). You can also [open the create-connector screen directly](https://chatgpt.com/plugins#settings/Connectors?create-connector=true&redirectAfter=%2Fplugins). Then enter: + + | Field | Value | + | --- | --- | + | Name | `Terminal49` | + | MCP server URL | `https://mcp.terminal49.com` | + | Authentication | `OAuth` | + + + Save the connector. ChatGPT opens the Terminal49 sign-in page in your browser. Log in with your Terminal49 account and approve access. + + + In a new chat, enable the **Terminal49** connector from the tools menu (with Developer mode active), then ask: + + > "Using Terminal49, search for container CAIU1234567 and summarize its status." + + + + +OpenAI has moved the Developer mode toggle between settings sections over time. If you don't see it under the connectors section, check **Settings → Security** (or search the [OpenAI Help Center](https://help.openai.com) for "developer mode"). + + +## Test your connection + +Ask ChatGPT: + +> "List the tools available in the Terminal49 MCP server and what they're for." + +It should list tools such as `search_container`, `track_container`, and `get_container`. See the [tools reference](/mcp/home#tools-reference) for the full list, and [Test Numbers](/api-docs/useful-info/test-numbers) for containers you can use during development. + +## Troubleshooting + +| Symptom | How to fix | +|---------|------------| +| No option to add a custom connector | Enable Developer mode; confirm your plan supports it, or ask your workspace admin | +| Connector fails to create | Confirm the URL is exactly `https://mcp.terminal49.com` (no path) | +| Sign-in window never opens | Pop-up blocked — allow pop-ups for chatgpt.com and retry | +| `401 Unauthorized` after connecting | Remove and re-add the connector to refresh the OAuth token | + +## Related guides + +- [MCP Overview](/mcp/home) – Tools, prompts, and resources reference +- [MCP Server Quickstart](/api-docs/in-depth-guides/mcp) – Full setup, including API-key and local stdio options +- [Other MCP clients](/mcp/setup/other-clients) – Generic configuration for any client diff --git a/docs/mcp/setup/claude-code.mdx b/docs/mcp/setup/claude-code.mdx new file mode 100644 index 00000000..a12598fc --- /dev/null +++ b/docs/mcp/setup/claude-code.mdx @@ -0,0 +1,67 @@ +--- +title: "Connect Claude Code to Terminal49" +sidebarTitle: "Claude Code" +description: "Connect Claude Code to the Terminal49 MCP server from your terminal with OAuth — no API key required." +keywords: + - "Terminal49 MCP server" + - "Claude Code" + - "claude mcp add" + - "OAuth" + - "container tracking" +--- +Connect Claude Code to the Terminal49 MCP server so it can answer questions with live container and shipment tracking data while you work in your terminal. + + +**No API key required.** The Terminal49 MCP server supports OAuth 2.1. When you authenticate, Claude Code opens a browser sign-in page — log in with your Terminal49 credentials and you're done. + + + +Using claude.ai or Claude Desktop instead? See the [Claude guide](/mcp/setup/claude). + + +## Add the server + + + + ```bash + claude mcp add --transport http terminal49 https://mcp.terminal49.com + ``` + + + Inside a Claude Code session, run `/mcp`, select **terminal49**, and choose **Authenticate**. Your browser opens the Terminal49 sign-in page; after you log in and approve access, the server shows as connected. + + + Ask Claude Code: + + > "Using Terminal49, search for container CAIU1234567 and summarize its status." + + + +## Alternative: install the Terminal49 plugin + +Instead of adding the MCP server directly, you can install the **Terminal49** plugin, which configures the same MCP connection and adds a `container-tracking` skill that teaches Claude Code how to choose and sequence the Terminal49 tools. See the [Agent plugins guide](/mcp/setup/agent-plugins) for install commands and details. + +## Test your connection + +Ask Claude Code: + +> "List the tools available in the Terminal49 MCP server and what they're for." + +It should list tools such as `search_container`, `track_container`, and `get_container`. See the [tools reference](/mcp/home#tools-reference) for the full list, and [Test Numbers](/api-docs/useful-info/test-numbers) for containers you can use during development. + +## Troubleshooting + +| Symptom | How to fix | +|---------|------------| +| Server missing from `/mcp` | Confirm it was added with `claude mcp list`; re-run the `claude mcp add` command if needed | +| `claude mcp add` fails | Confirm the URL is exactly `https://mcp.terminal49.com` (no path) and the transport is `http` | +| Sign-in window never opens | Pop-up blocked or no default browser — allow pop-ups and retry **Authenticate** from `/mcp` | +| `401 Unauthorized` after connecting | Run `/mcp`, select **terminal49**, and re-authenticate to refresh the OAuth token | + +## Related guides + +- [Claude](/mcp/setup/claude) – claude.ai and Claude Desktop connectors +- [Agent plugins](/mcp/setup/agent-plugins) – Terminal49 plugin with the `container-tracking` skill +- [MCP Overview](/mcp/home) – Tools, prompts, and resources reference +- [MCP Server Quickstart](/api-docs/in-depth-guides/mcp) – Full setup, including API-key and local stdio options +- [Other MCP clients](/mcp/setup/other-clients) – Generic configuration for any client diff --git a/docs/mcp/setup/claude.mdx b/docs/mcp/setup/claude.mdx new file mode 100644 index 00000000..017df149 --- /dev/null +++ b/docs/mcp/setup/claude.mdx @@ -0,0 +1,77 @@ +--- +title: "Connect Claude to Terminal49" +sidebarTitle: "Claude" +description: "Connect claude.ai or Claude Desktop to the Terminal49 MCP server with OAuth — no API key required." +keywords: + - "Terminal49 MCP server" + - "Claude connector" + - "claude.ai custom connector" + - "Claude Desktop" + - "OAuth" + - "container tracking" +--- +Connect Claude to the Terminal49 MCP server so it can answer questions with live container and shipment tracking data. + + +**No API key required.** The Terminal49 MCP server supports OAuth 2.1. When you connect, Claude opens a browser sign-in page — log in with your Terminal49 credentials and you're done. + + + +Using Claude Code? See the [Claude Code guide](/mcp/setup/claude-code) — it's one command from your terminal. + + +## claude.ai and Claude Desktop + +Custom connectors are managed in the same place on claude.ai (web) and in the Claude Desktop app. + + + + In Claude, go to **Settings → Connectors**. On claude.ai you can also [open the Add custom connector dialog directly](https://claude.ai/new?modal=add-custom-connector#settings/customize-connectors) and skip the next click. + + + Click **Add custom connector**, then enter: + + | Field | Value | + | --- | --- | + | Name | `Terminal49` | + | URL | `https://mcp.terminal49.com` | + + Leave the advanced OAuth fields (Client ID / Client Secret) empty — Claude registers itself automatically. + + + Click **Connect**. A browser window opens with the Terminal49 sign-in page. Log in with your Terminal49 account and approve access. + + + In a new chat, open the tools menu and make sure **Terminal49** is enabled. Then ask: + + > "Using Terminal49, search for container CAIU1234567 and summarize its status." + + + + +Custom connectors are available on Claude Free, Pro, Max, Team, and Enterprise plans (Free is limited to one custom connector). On Team and Enterprise plans, an organization Owner must add the connector first under **Organization Settings → Connectors**; each member then connects their own Terminal49 account. + + +## Test your connection + +Ask Claude: + +> "List the tools available in the Terminal49 MCP server and what they're for." + +Claude should list tools such as `search_container`, `track_container`, and `get_container`. See the [tools reference](/mcp/home#tools-reference) for the full list, and [Test Numbers](/api-docs/useful-info/test-numbers) for containers you can use during development. + +## Troubleshooting + +| Symptom | How to fix | +|---------|------------| +| Connector fails to add | Confirm the URL is exactly `https://mcp.terminal49.com` (no path) | +| Sign-in window never opens | Pop-up blocked — allow pop-ups for claude.ai and retry | +| `401 Unauthorized` after connecting | Disconnect and reconnect the connector to refresh the OAuth token | +| Connector not selectable in chat | Enable it in the chat's tools menu; on Team/Enterprise ask an Owner to enable it for the organization | + +## Related guides + +- [Claude Code](/mcp/setup/claude-code) – Add the server from your terminal +- [MCP Overview](/mcp/home) – Tools, prompts, and resources reference +- [MCP Server Quickstart](/api-docs/in-depth-guides/mcp) – Full setup, including API-key and local stdio options +- [Other MCP clients](/mcp/setup/other-clients) – Generic configuration for any client diff --git a/docs/mcp/setup/cursor.mdx b/docs/mcp/setup/cursor.mdx new file mode 100644 index 00000000..8e8d8f41 --- /dev/null +++ b/docs/mcp/setup/cursor.mdx @@ -0,0 +1,93 @@ +--- +title: "Connect Cursor to Terminal49" +sidebarTitle: "Cursor" +description: "Connect the Cursor IDE to the Terminal49 MCP server with OAuth — no API key required." +keywords: + - "Terminal49 MCP server" + - "Cursor MCP" + - "mcp.json" + - "OAuth" + - "container tracking" +--- +Connect Cursor to the Terminal49 MCP server so its AI agent can answer questions with live container and shipment tracking data. + + +**No API key required.** The Terminal49 MCP server supports OAuth 2.1. When you connect, Cursor opens a browser sign-in page — log in with your Terminal49 credentials and you're done. + + +## Add the server + + + + The fastest way is the one-click install button — it opens Cursor with the Terminal49 server configuration pre-filled; just confirm to install: + + [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=terminal49&config=eyJ1cmwiOiJodHRwczovL21jcC50ZXJtaW5hbDQ5LmNvbSJ9) + + Alternatively, add the server manually to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` to make it available in every project): + + ```json + { + "mcpServers": { + "terminal49": { + "url": "https://mcp.terminal49.com" + } + } + } + ``` + + You can also add it from the UI: **Cursor Settings → MCP → Add new MCP server**, using the same URL. + + + Cursor detects that the server requires authentication and shows a **Needs login** / **Connect** action next to it in **Cursor Settings → MCP**. Click it — your browser opens the Terminal49 sign-in page. Log in and approve access. Cursor stores and refreshes the tokens automatically. + + + Open the agent chat and ask: + + > "Using Terminal49, search for container CAIU1234567 and summarize its status." + + + +## Alternative: install the Terminal49 plugin + +Instead of adding the MCP server directly, you can install the **Terminal49** plugin, which configures the same MCP connection and adds a `container-tracking` skill that teaches Cursor's agent how to choose and sequence the Terminal49 tools. See the [Agent plugins guide](/mcp/setup/agent-plugins) for install steps and details. + +## API key alternative + +If you prefer a fixed credential (for example on a shared machine where the browser flow isn't practical), create an API key in the [developer portal](https://app.terminal49.com/developers/api-keys) and pass it as a header instead: + +```json +{ + "mcpServers": { + "terminal49": { + "url": "https://mcp.terminal49.com", + "headers": { + "Authorization": "Token YOUR_API_KEY" + } + } + } +} +``` + +## Test your connection + +Ask the Cursor agent: + +> "List the tools available in the Terminal49 MCP server and what they're for." + +It should list tools such as `search_container`, `track_container`, and `get_container`. See the [tools reference](/mcp/home#tools-reference) for the full list, and [Test Numbers](/api-docs/useful-info/test-numbers) for containers you can use during development. + +## Troubleshooting + +| Symptom | How to fix | +|---------|------------| +| Server shows as disconnected | Confirm the URL is exactly `https://mcp.terminal49.com` (no path), then toggle the server off and on in **Cursor Settings → MCP** | +| Sign-in window never opens | Update Cursor to the latest version, then retry the **Connect** action | +| `401 Unauthorized` | Re-run the login from **Cursor Settings → MCP**, or check the `Authorization: Token YOUR_API_KEY` header if you use an API key | +| Tools list is empty | Restart Cursor so it reloads `mcp.json` | + +## Related guides + +- [Agent plugins](/mcp/setup/agent-plugins) – Terminal49 plugin with the `container-tracking` skill +- [MCP Overview](/mcp/home) – Tools, prompts, and resources reference +- [MCP Server Quickstart](/api-docs/in-depth-guides/mcp) – Full setup, including API-key and local stdio options +- [Other MCP clients](/mcp/setup/other-clients) – Generic configuration for any client diff --git a/docs/mcp/setup/microsoft-copilot.mdx b/docs/mcp/setup/microsoft-copilot.mdx new file mode 100644 index 00000000..d8336936 --- /dev/null +++ b/docs/mcp/setup/microsoft-copilot.mdx @@ -0,0 +1,73 @@ +--- +title: "Connect Microsoft Copilot to Terminal49" +sidebarTitle: "Microsoft Copilot" +description: "Add the Terminal49 MCP server as a tool in Microsoft Copilot Studio agents using OAuth 2.0 with dynamic discovery — no API key required." +keywords: + - "Terminal49 MCP server" + - "Microsoft Copilot Studio" + - "Copilot MCP" + - "OAuth" + - "dynamic client registration" + - "container tracking" +--- +Add the Terminal49 MCP server as a tool in a Microsoft Copilot Studio agent so Copilot can answer questions with live container and shipment tracking data. Agents built in Copilot Studio can then be published to Microsoft 365 Copilot, Teams, and other channels. + + +**No API key required.** The Terminal49 MCP server supports OAuth 2.1 with Dynamic Client Registration, which maps to Copilot Studio's **OAuth 2.0 → Dynamic discovery** authentication option. Users sign in with their Terminal49 credentials in the browser. + + +## Prerequisites + +- Access to [Microsoft Copilot Studio](https://copilotstudio.microsoft.com) with permission to edit an agent and add tools. +- The MCP tool configuration wizard enabled in your environment (Microsoft is rolling it out by region and tenant; if selecting the MCP option only opens documentation, the wizard isn't enabled for your tenant yet). + +## Add the server to an agent + + + + In Copilot Studio, open your agent and go to the **Tools** page, then select **+ Add a tool**. + + + Select **+ New tool → Model Context Protocol**, then enter: + + | Field | Value | + | --- | --- | + | Server name | `Terminal49` | + | Server description | `Live container and shipment tracking data from Terminal49` | + | Server URL | `https://mcp.terminal49.com` | + + + Under **Authentication**, select **OAuth 2.0** and choose **Dynamic discovery**. Copilot Studio discovers Terminal49's authorization server and registers itself automatically — you don't need to enter client credentials. + + + Create the tool, then select **Connect** (or open the connection manager) and sign in with your Terminal49 account in the browser window that opens. + + + Make sure the tool is enabled for the agent, then ask in the test pane: + + > "Using Terminal49, search for container CAIU1234567 and summarize its status." + + + +## Test your connection + +Ask the agent: + +> "List the tools available in the Terminal49 MCP server and what they're for." + +It should list tools such as `search_container`, `track_container`, and `get_container`. See the [tools reference](/mcp/home#tools-reference) for the full list, and [Test Numbers](/api-docs/useful-info/test-numbers) for containers you can use during development. + +## Troubleshooting + +| Symptom | How to fix | +|---------|------------| +| MCP option only opens a documentation page | The MCP config wizard isn't enabled for your region or tenant yet — check with your Microsoft admin | +| Connection fails during discovery | Confirm the URL is exactly `https://mcp.terminal49.com` (no path) and that OAuth 2.0 → Dynamic discovery is selected | +| `401 Unauthorized` | Re-authenticate the connection from the agent's tool settings | +| End users are asked to sign in | Expected — each user authorizes with their own Terminal49 account on first use | + +## Related guides + +- [MCP Overview](/mcp/home) – Tools, prompts, and resources reference +- [MCP Server Quickstart](/api-docs/in-depth-guides/mcp) – Full setup, including API-key and local stdio options +- [Other MCP clients](/mcp/setup/other-clients) – Generic configuration for any client diff --git a/docs/mcp/setup/other-clients.mdx b/docs/mcp/setup/other-clients.mdx new file mode 100644 index 00000000..65a6b7dc --- /dev/null +++ b/docs/mcp/setup/other-clients.mdx @@ -0,0 +1,73 @@ +--- +title: "Connect Any MCP Client to Terminal49" +sidebarTitle: "Other MCP clients" +description: "Generic configuration for connecting any MCP-compatible client to the Terminal49 MCP server, with OAuth 2.1 or an API key." +keywords: + - "Terminal49 MCP server" + - "MCP client" + - "streamable HTTP" + - "OAuth 2.1" + - "API key" + - "container tracking" +--- +Any client that supports MCP over streamable HTTP can connect to the Terminal49 MCP server. This page gives the generic settings; for step-by-step guides see [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), and [Agent plugins](/mcp/setup/agent-plugins) (Claude Code, Cursor, Codex, GitHub Copilot CLI). + +## Server details + +| Setting | Value | +| --- | --- | +| Server URL | `https://mcp.terminal49.com` | +| Transport | HTTP (streamable) | +| Authentication | OAuth 2.1 (recommended) or API key header | + +Always use the root origin `https://mcp.terminal49.com` — it is the canonical OAuth resource identifier, so OAuth clients bind to the correct token audience. + +## OAuth 2.1 (recommended — no API key) + +Point your client at `https://mcp.terminal49.com` with no credentials. Clients that implement MCP authorization discover everything automatically: + +- Protected resource metadata is served at `https://mcp.terminal49.com/.well-known/oauth-protected-resource`, which points to the authorization server at `https://auth.terminal49.com`. +- Dynamic Client Registration is supported, so clients register themselves — no pre-configured client ID or secret is needed. +- The flow is authorization code with PKCE: the client opens your browser, you sign in with your Terminal49 credentials and approve access, and the client stores and refreshes tokens automatically. + +```json +{ + "url": "https://mcp.terminal49.com" +} +``` + +## API key (for clients without OAuth support) + +If your client can't run a browser OAuth flow (for example, a headless integration), create an API key in the [developer portal](https://app.terminal49.com/developers/api-keys) and send it in the `Authorization` header with the `Token` scheme: + +```json +{ + "url": "https://mcp.terminal49.com", + "headers": { + "Authorization": "Token YOUR_API_KEY" + } +} +``` + +You can verify connectivity with `curl`: + +```bash +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}' +``` + + +Use the `Token` scheme for API keys. The `Bearer` scheme is used for OAuth access tokens, which OAuth-capable clients obtain automatically during sign-in. + + +The same [rate limits](/api-docs/in-depth-guides/rate-limiting) apply to MCP endpoints as the REST API. + +## Related guides + +- [MCP Overview](/mcp/home) – Tools, prompts, and resources reference +- [MCP Server Quickstart](/api-docs/in-depth-guides/mcp) – Full setup, local stdio development, deployment +- [Test Numbers](/api-docs/useful-info/test-numbers) – Containers for testing diff --git a/docs/mcp/setup/vs-code.mdx b/docs/mcp/setup/vs-code.mdx new file mode 100644 index 00000000..b0e67794 --- /dev/null +++ b/docs/mcp/setup/vs-code.mdx @@ -0,0 +1,74 @@ +--- +title: "Connect VS Code to Terminal49" +sidebarTitle: "VS Code" +description: "Connect VS Code and GitHub Copilot agent mode to the Terminal49 MCP server with OAuth — no API key required." +keywords: + - "Terminal49 MCP server" + - "VS Code MCP" + - "GitHub Copilot" + - "mcp.json" + - "OAuth" + - "container tracking" +--- +Connect VS Code to the Terminal49 MCP server so GitHub Copilot's agent mode can answer questions with live container and shipment tracking data. + + +**No API key required.** The Terminal49 MCP server supports OAuth 2.1. When you connect, VS Code opens a browser sign-in page — log in with your Terminal49 credentials and you're done. + + +## Prerequisites + +- VS Code 1.101 or later (required for remote MCP servers with OAuth). +- GitHub Copilot enabled in VS Code. + +## Add the server + + + + Add the server to `.vscode/mcp.json` in your workspace: + + ```json + { + "servers": { + "terminal49": { + "type": "http", + "url": "https://mcp.terminal49.com" + } + } + } + ``` + + Alternatively, run **MCP: Add Server** from the Command Palette, choose **HTTP**, and enter the same URL. + + + Save the file, then use the **Start** CodeLens above the server entry in `mcp.json` (or **MCP: List Servers** from the Command Palette). When VS Code prompts you to authenticate, allow it — your browser opens the Terminal49 sign-in page. Log in and approve access. + + + Open Copilot Chat in **agent mode**, confirm the Terminal49 tools are enabled in the tools picker, and ask: + + > "Using Terminal49, search for container CAIU1234567 and summarize its status." + + + +## Test your connection + +Ask Copilot in agent mode: + +> "List the tools available in the Terminal49 MCP server and what they're for." + +It should list tools such as `search_container`, `track_container`, and `get_container`. See the [tools reference](/mcp/home#tools-reference) for the full list, and [Test Numbers](/api-docs/useful-info/test-numbers) for containers you can use during development. + +## Troubleshooting + +| Symptom | How to fix | +|---------|------------| +| Server won't start | Confirm the URL is exactly `https://mcp.terminal49.com` (no path) and VS Code is 1.101+ | +| Never prompted to sign in | Use the **Auth** action from the CodeLens above the server in `mcp.json`, or restart the server | +| `401 Unauthorized` | Re-authenticate via the server's CodeLens actions | +| Tools missing in chat | Switch Copilot Chat to agent mode and enable the Terminal49 tools in the tools picker | + +## Related guides + +- [MCP Overview](/mcp/home) – Tools, prompts, and resources reference +- [MCP Server Quickstart](/api-docs/in-depth-guides/mcp) – Full setup, including API-key and local stdio options +- [Other MCP clients](/mcp/setup/other-clients) – Generic configuration for any client