Repository navigation
docs(advanced): connect your AI assistant (GH #3623) - #32
Closed
niekcandaele wants to merge 3 commits into
Closed
niekcandaele wants to merge 3 commits into
niekcandaele wants to merge 3 commits into
Conversation
Documents the Takaro MCP endpoint for operators: the endpoint URL and its discovery document, the URL-only setup for Claude Code, Claude.ai and ChatGPT, the pre-registered fallback clients for Cursor and VS Code, what the assistant can and cannot do, domain selection, the destructive-call brake, the response budget, and troubleshooting. Ships alongside gettakaro/takaro#3623 (epic gettakaro/takaro#3616), which extends the maintainer-side manual OAuth checklist in that repo. Claude-Session: https://claude.ai/code/session_01LRsE6g3Copo9nYfxCuP5Z6
A UX review of the first draft found the page had exactly one assistant a reader could follow to completion. Fixes: - An "which assistant do you have?" table up front, with an honest verification status per assistant, so a reader finds their own path without reading the whole page. - Claude.ai and ChatGPT get real setup sections and a verification step instead of one sentence each. - Cursor and VS Code get told what to actually do with the client id, and are told plainly that if their assistant has no client-id setting it is not supported yet. - New: how to disconnect and reconnect, how to revoke the grant, and a self-hosted section carrying the allowlist rule (no wildcard) and the two environment variables that were previously scattered through user prose. - Troubleshooting gains the dominant self-hosted failure (browser cannot reach the login server), quotes the real "Unknown operation id" message, and is split into linkable headings. - Drops the "harness" jargon, the curl diagnostic from the main flow, and the bolded-bullet lists in favour of prose. Also links the page from advanced/api.md, which was the only other place a reader looking for programmatic access would land. Claude-Session: https://claude.ai/code/session_01LRsE6g3Copo9nYfxCuP5Z6
An independent review against the implementation caught four overstatements: - The endpoint is modern-only (`legacy: 'reject'`, revision 2026-07-28). An older client can complete the OAuth flow and still have every tool call refused, so it belongs in "what you need". - `claude mcp add` does not itself start the login. Say to run `/mcp` in Claude Code. - Nothing forces search-before-call: a correctly guessed operation id runs. The error only fires on an id the endpoint does not expose. - "Every change appears in your event log" is stronger than the code: an MCP call is audited exactly as the same action is from the dashboard, no more. Also separates ChatGPT from Codex, and stops asserting what Cursor and VS Code do or do not document — both describe a client-id setting; what is unverified is whether the flow completes against Takaro. Claude-Session: https://claude.ai/code/session_01LRsE6g3Copo9nYfxCuP5Z6
Contributor
Author
|
Superseded: this page now lives in the Astro site as |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds
docs/advanced/connect-your-ai-assistant.md: the operator-facing guide to Takaro's MCP endpoint.Ships with gettakaro/takaro#3623, the last ticket of epic gettakaro/takaro#3616. That epic added an MCP endpoint at
/mcpinside app-api, authorised through Keycloak, with four tools (search_api,describe_operation,call_api,list_domains), a destructive-call brake and a response budget. This page is the half of #3623 that belongs in the public docs; the other half — the maintainer-side manual OAuth checklist — is a PR against the Takaro monorepo.What the page covers
https://api.takaro.io/mcp;<BASE_URL>/mcpself-hosted) and the protected-resource discovery document, so no login host is hardcoded.takaro-mcp-cursorandtakaro-mcp-vscodewith their exact redirect URIs, linked to the realm file they come from. Marked explicitly as not yet verified end to end.Notes for the reviewer
sidebar_position: 8, chosen so no existing page's frontmatter has to change (generic-connector-protocol.mdxis 7;discord-integration.mdisunlisted). The only other file touched isadvanced/api.md, which gains a one-line pointer — it was the only other place a reader looking for programmatic access would land.claude mcp adddoes not itself sign you in; nothing forces search-before-call; auditing matches the dashboard rather than "every change is logged").https://api.takaro.io/mcpis derived from the endpoint being/mcpon the API'sBASE_URL, plus the API host this docs site already publishes inadvanced/api.md. Worth a second pair of eyes.npm ci && npm run build && npm run typecheckall pass locally (the build, withonBrokenLinks: throw, is this repo's CI gate).Draft on purpose: a human should confirm the hosted endpoint URL and the Claude.ai / ChatGPT wording before this goes live, and the fallback-client rows are still unverified (gettakaro/takaro#3623 AC3).
https://claude.ai/code/session_01LRsE6g3Copo9nYfxCuP5Z6