docs: add per-tool MCP setup guides (OAuth 2.1, no API key) - #302
Conversation
Add setup guides for connecting Claude (claude.ai, Desktop, Claude Code), ChatGPT, Cursor, Microsoft Copilot Studio, VS Code (GitHub Copilot), and any other MCP client to the Terminal49 MCP server. The hosted server now supports OAuth 2.1 (authorization code + PKCE with dynamic client registration via auth.terminal49.com), so the guides lead with browser sign-in using Terminal49 credentials — no API key required. API-key header auth remains documented as a fallback for clients without OAuth support and for local stdio development. Update the MCP overview and quickstart to remove the stale 'API key only / OAuth not available' language, and add the new pages to the MCP tab nav in docs.json under a Setup Guides group. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QyDxMSSqV5YouCP4akxXi4
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
|
|
||
| **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. |
There was a problem hiding this comment.
When T49_MCP_AUTHKIT_ENABLED is not true, the hosted handler omits OAuth discovery from its authentication challenge and does not resolve OAuth Bearer tokens. In that deployment state, a client following this new no-key flow either never opens sign-in or returns to a 401 after sign-in, so this unconditional guidance should be published only with AuthKit enabled or should state that prerequisite.
Prompt To Fix With AI
This is a comment left during a code review.
Path: docs/api-docs/in-depth-guides/mcp.mdx
Line: 51-55
Comment:
**OAuth Depends on Deployment Flag**
When `T49_MCP_AUTHKIT_ENABLED` is not `true`, the hosted handler omits OAuth discovery from its authentication challenge and does not resolve OAuth Bearer tokens. In that deployment state, a client following this new no-key flow either never opens sign-in or returns to a `401` after sign-in, so this unconditional guidance should be published only with AuthKit enabled or should state that prerequisite.
How can I resolve this? If you propose a fix, please make it concise.Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b8d0afbc48
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| The manual configurations below use an API key instead. Use them for clients or environments where the browser OAuth flow isn't practical. | ||
|
|
||
| ### Claude Desktop (manual, API key) |
There was a problem hiding this comment.
Claude Desktop's native connector cannot consume static API-key headers from this configuration; the repository's client-specific source explicitly says claude.ai and Claude Desktop must use the WorkOS OAuth flow (packages/mcp/WORKOS_MCP_SETUP.md:89-91). Labeling this as a supported manual fallback sends users to edit a config the connector does not use, so remove this section or document a genuinely supported proxy/stdio route instead.
AGENTS.md reference: AGENTS.md:L77-L80
Useful? React with 👍 / 👎.
| curl -X POST https://mcp.terminal49.com \ | ||
| -H "Authorization: Token $T49_API_TOKEN" \ | ||
| -H "Content-Type: application/json" \ | ||
| -d '{"jsonrpc":"2.0","method":"tools/list","id":1}' |
There was a problem hiding this comment.
When an API-key user copies this connectivity check, curl sends Accept: */*, but an MCP Streamable HTTP POST must accept both JSON and event streams, so the SDK transport rejects the request instead of listing tools. The repository's working MCP client sends Accept: application/json, text/event-stream (and the protocol-version header) in packages/mcp/scripts/oauth-test-client.mjs:549-552; include those headers here so the advertised verification command is copy-pasteable.
AGENTS.md reference: docs/AGENTS.md:L33-L38
Useful? React with 👍 / 👎.
| <Step title="Use it in a chat"> | ||
| In a new chat, enable the **Terminal49** connector from the tools menu (with Developer mode active), then ask: | ||
|
|
||
| > "Using Terminal49, track container CAIU1234567 with Maersk." |
There was a problem hiding this comment.
For a newly connected account where this placeholder container is not already tracked, this prompt invokes track_container, the server's only write tool, and creates a real tracking request (packages/mcp/src/server.ts:87). Because CAIU1234567 is not one of the deterministic TEST-TR-* numbers documented for testing, following the setup guide can add a failed or pending record and consume a tracking slot on limited plans; use the read-only tools-list prompt here, or use a documented test number with the TEST SCAC.
AGENTS.md reference: docs/AGENTS.md:L33-L38
Useful? React with 👍 / 👎.
…nly test prompts, curl Accept headers - Remove the Claude Desktop manual API-key config from the MCP quickstart: claude.ai/Claude Desktop must use the OAuth connector flow (see packages/mcp/WORKOS_MCP_SETUP.md); point API-key local dev at the stdio server - Replace the connection-test prompt on all setup pages and the MCP overview with a read-only search_container prompt, since track_container is the server's only write tool and creates a real tracking request - Add Accept and MCP-Protocol-Version headers to the curl connectivity checks, matching the headers the OAuth test client sends Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QyDxMSSqV5YouCP4akxXi4
…or one-click install - Move Claude Code setup out of the Claude guide into its own page (mcp/setup/claude-code) and add it to the Setup Guides nav, the MCP overview list/cards, and cross-references in related guides - claude.mdx: link directly to the claude.ai Add custom connector dialog - chatgpt.mdx: link directly to the ChatGPT create-connector screen - cursor.mdx: add a one-click Install MCP Server button (Cursor install-link with base64 server config), keeping manual mcp.json steps Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QyDxMSSqV5YouCP4akxXi4
…-plugins Add install instructions for the Terminal49 plugin marketplace: - Claude Code and Cursor setup guides get an 'Alternative: install the Terminal49 plugin' section with the marketplace install commands - MCP overview gets an 'Agent plugins' section covering Claude Code, Codex, GitHub Copilot CLI, and Cursor installs The plugin bundles the hosted MCP server connection with a shared container-tracking skill; auth remains the same browser OAuth flow. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QyDxMSSqV5YouCP4akxXi4
- Add docs/mcp/setup/agent-plugins.mdx with per-platform install tabs (Claude Code, Cursor, Codex, GitHub Copilot CLI), skill overview, troubleshooting, and related guides - Replace the Agent plugins section on the MCP overview with a setup-guide card and a TL;DR list entry - Shrink the plugin alternative sections in the Claude Code and Cursor guides to short pointers so install commands live in one place - Add the page to the Setup Guides nav group and to guide lists in the MCP quickstart and other-clients pages Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QyDxMSSqV5YouCP4akxXi4
2 participants
Requested by Akshay Dodeja · Slack thread
Before: The MCP docs only covered Claude Desktop and Cursor, and told users an API key was required ("API key only — OAuth not required for this release", "OAuth is not available for the hosted MCP server yet").
After: Per-tool setup guides for Claude (claude.ai, Claude Desktop, Claude Code), ChatGPT, Cursor, Microsoft Copilot (Copilot Studio), VS Code (GitHub Copilot), and a generic "Other MCP clients" page — all leading with OAuth 2.1: paste
https://mcp.terminal49.com, sign in with Terminal49 credentials in the browser, done. No API key needed. API-key header auth (Authorization: Token ...) stays documented as a fallback for clients without OAuth support and for local stdio development.How:
docs/mcp/setup/{claude,chatgpt,cursor,microsoft-copilot,vs-code,other-clients}.mdx(each: OAuth-first steps, test prompts, troubleshooting, related links).docs/mcp/home.mdx— OAuth-first TL;DR, setup-guide cards, rewrote the Authentication section, removed the "OAuth is not available yet" note.docs/api-docs/in-depth-guides/mcp.mdx— OAuth-first auth section and client config section (manual API-key configs kept as fallback), fixed the stale Cursor config shape, updated prerequisites and 401 troubleshooting.docs/docs.jsonunder a new Setup Guides group in the MCP tab.OAuth support verified against the live server:
https://mcp.terminal49.com/.well-known/oauth-protected-resourcepoints tohttps://auth.terminal49.com, which advertises authorization code + PKCE (S256), refresh tokens, and dynamic client registration.Checks run:
git diff --check,docs.jsonJSON parse,npx mintlify broken-links(no broken links), stale-phrasing grep.🤖 Generated with Claude Code
https://claude.ai/code/session_01QyDxMSSqV5YouCP4akxXi4
Generated by Claude Code
Greptile Summary
This PR adds OAuth-first setup guides for the Terminal49 MCP server. The main changes are:
Confidence Score: 5/5
The documentation is mergeable after the OAuth deployment prerequisite is clarified.
docs/api-docs/in-depth-guides/mcp.mdx
Important Files Changed
Prompt To Fix All With AI
Reviews (1): Last reviewed commit: "docs: add per-tool MCP setup guides with..." | Re-trigger Greptile