External agent setup docs (Claude Code, opencode, generic MCP) #55

New issue

Open

opened 2026-06-14 19:52:08 +00:00 by james · 0 comments

james commented

2026-06-14 19:52:08 +00:00

Owner

Document how to wire common external agent clients to a Carol instance via the MCP endpoint and a Personal Access Token.

Scope

Add docs/agent-setup.md (or a section in an existing docs page if a better home exists) with worked recipes:
- Claude Code: issue a PAT in settings, paste the config snippet into claude_desktop_config.json (mcpServers entry with the URL and Authorization header), verify with a sample read-tool query.
- opencode: equivalent recipe per opencode's MCP configuration mechanism.
- Generic MCP client: the endpoint URL, the Authorization: Bearer header shape, what to expect at handshake.
A short troubleshooting section: token expiry, 401 responses, how to revoke and reissue.
A pointer to the relevant ADRs (agent-runtime, tool-granularity, PAT) so a curious operator can read the design decisions.

Acceptance criteria

Docs page exists with at least two worked recipes (Claude Code + one other).
A new user can follow the Claude Code recipe end-to-end and run one read-tool query without help.
Linked from the main README's docs index.

Part of epic #47. Depends on the MCP server endpoint and Personal Access Tokens.

Document how to wire common external agent clients to a Carol instance via the MCP endpoint and a Personal Access Token. ## Scope - Add `docs/agent-setup.md` (or a section in an existing docs page if a better home exists) with worked recipes: - **Claude Code**: issue a PAT in settings, paste the config snippet into `claude_desktop_config.json` (`mcpServers` entry with the URL and Authorization header), verify with a sample read-tool query. - **opencode**: equivalent recipe per opencode's MCP configuration mechanism. - **Generic MCP client**: the endpoint URL, the `Authorization: Bearer` header shape, what to expect at handshake. - A short troubleshooting section: token expiry, 401 responses, how to revoke and reissue. - A pointer to the relevant ADRs (agent-runtime, tool-granularity, PAT) so a curious operator can read the design decisions. ## Acceptance criteria - [ ] Docs page exists with at least two worked recipes (Claude Code + one other). - [ ] A new user can follow the Claude Code recipe end-to-end and run one read-tool query without help. - [ ] Linked from the main README's docs index. Part of epic #47. Depends on the MCP server endpoint and Personal Access Tokens.

james added the

area:service

label

2026-06-14 19:52:54 +00:00