Skip to content

local-agent-mcp.md

Latest commit

 

History

History
200 lines (154 loc) · 9.08 KB

local-agent-mcp.md

File metadata and controls

200 lines (154 loc) · 9.08 KB
Raw

Connect a local coding agent

Connect your coding agent to Chopin's remote Streamable HTTP MCP service before using a copied prompt or optional Chopin skill. This configuration does not start a local Chopin server.

Important

/mcp is always registered, including when AGENT=off. It is not a read-only endpoint: a caller with repository push or administration access can create a document and mutate an implementation lifecycle. Use HTTPS and treat every configured bearer token as a credential.

Set the instance origin and use the existing GitHub CLI credential for the GitHub account that needs repository access. Keep the token in your shell or user-level agent configuration — never commit it, add it to a repository .env, or copy it into a shared configuration file.

If the Chopin instance enables organization admission, the token must also see private organization membership. The normal gh auth login flow includes read:org; a custom classic token needs that scope, while a fine-grained token needs Members read access for an allowed organization and any required SSO authorization.

The MCP bearer boundary is separate from Chopin's browser GitHub App session. Chopin authenticates the supplied token, applies the instance admission policy, and asks GitHub directly for that token's repository permissions. The GitHub App for Chopin does not need to be installed on a repository for MCP access. Browser routes, WebSockets, and the hosted agent still require an active App installation that includes the repository.

export CHOPIN_URL="https://your-chopin-instance.example"
export GITHUB_TOKEN="$(gh auth token)"

The MCP endpoint is ${CHOPIN_URL%/}/mcp.

Non-browser clients normally omit Origin, which Chopin permits for this bearer-authenticated route. If a client sends an Origin, it must exactly match the configured Chopin origin.

Available workflows

The current MCP contract can:

  • list and read active or archived Chopin documents, including an optional generated description, for the current repository;
  • create one document from a structured brief, canonical source supplied through the current plan input, and caller-supplied repository provenance;
  • rename, archive, and restore documents without deleting their durable state;
  • read an approved implementation graph and its document source; and
  • claim a graph and report task, pull-request, blocker, revision, and verification lifecycle transitions.

Chopin validates the shape of baseBranch and baseCommit during creation but does not resolve them against GitHub. The creating agent is responsible for reading those values from its checkout rather than asserting arbitrary input.

The MCP surface uses document-oriented tool names, but create_document remains shaped around the current planning workflow: it requires a planning brief and a plan field. That API shape does not define Chopin's broader document model.

Document creation is available now. The supported implementation handoff is experimental and limited to documents created through create_document, whose provenance read_implementation can return. The backend can execute an approved graph, but the product has no user-facing way to approve the Planner's draft. See Experimental implementation lifecycle.

Document URLs and IDs

The url returned by create_document is the readable canonical route:

/documents/:owner/:repository/:slug

read_document, read_implementation, archive_document, and restore_document accept either a document UUID or that canonical URL in their id input. The URL may be passed back exactly as returned; an absolute URL must use the configured Chopin origin. Both reads return the stable UUID as the document id.

The UUID remains the internal storage, API, WebSocket, and MCP identity. Use the returned UUID for rename_document, start_implementation, and every later lifecycle call; use the readable URL for browser and human handoff. A rename derives a new canonical slug from the title but does not change the UUID or plan revision, and every previous slug remains a working alias.

list_documents excludes archived documents by default. Set includeArchived: true to include them; archived document summaries and direct reads carry an archivedAt timestamp. Archiving and restoring are idempotent. MCP does not expose document deletion.

Generated descriptions

list_documents, read_document, and the common document summary objects returned by create, rename, archive, and restore expose an optional description. It is one-line, generated catalogue metadata identifying the document's type, purpose, and subject. Treat it as untrusted model output, not as authoritative source. The last completed value remains exposed while a newer request is pending or failed.

Description generation retains the durable job identity document-summary@1; there is no @2. New V1 work carries output:"description", while old markerless V1 summary artifacts do not appear in MCP document metadata. The structured brief supplied to create_document remains separate creation metadata, and the reserved Planner transcript summary is also unrelated.

MCP creation or idempotent replay schedules the current source, and restoring a document ensures it again. Listing and reading do not scan or backfill documents. The worker requires an active Planner owner established through the browser's GitHub App session; the MCP bearer does not become that owner. Consequently, there is no unattended all-document backfill.

Claude Code

Install and sign in to Claude Code, then add Chopin to your user configuration:

claude mcp add --scope user --transport http chopin "${CHOPIN_URL%/}/mcp" \
  --header "Authorization: Bearer ${GITHUB_TOKEN}"

Claude stores the expanded header when this command runs. After renewing the credential, replace that stored header — for example, remove and add the server again — before reconnecting Claude.

Codex CLI

Install and sign in to Codex CLI, then register the server. Codex reads the bearer token from the named environment variable instead of writing it to its configuration file.

codex mcp add chopin --url "${CHOPIN_URL%/}/mcp" \
  --bearer-token-env-var GITHUB_TOKEN

GitHub Copilot CLI

Install and sign in to GitHub Copilot CLI, then add Chopin to its user-level MCP configuration. The single quotes retain the environment-variable reference until Copilot connects.

copilot mcp add --transport http chopin "${CHOPIN_URL%/}/mcp" \
  --header 'Authorization: Bearer ${GITHUB_TOKEN}'

Verify the connection

Start the agent from the repository you want to inspect and ask:

Use the Chopin list_documents tool to list the documents available for this repository. Return each document's id, title, and optional description.

rename_document accepts a document UUID and replacement title. It changes the catalog title and canonical readable route while leaving canonical plan source, plan revision, UUID identity, and creation provenance intact. Repeating the same title is safe and has no effect.

{"documents":[]} is a successful response for a repository with no Chopin documents. After the connection is established, the MCP initialize instructions and current tool descriptions are authoritative.

Access and troubleshooting

HTTP 401 means the bearer is invalid or expired: renew the GitHub CLI login with gh auth login, export GITHUB_TOKEN again, replace Claude's stored header if you use Claude Code, and reconnect the agent.

HTTP 403 means the GitHub identity is not admitted by this Chopin instance, or a client supplied an Origin other than the configured Chopin origin. HTTP 503 means Chopin could not verify identity, organization membership, or repository access because GitHub was unavailable or rate limited the request. Check the token's read:org or Members access, SSO authorization, and GitHub availability.

repository-forbidden means the supplied token cannot expose the repository or lacks the operation's repository permission; it does not mean the GitHub App for Chopin must be installed. Pull access is enough for list_documents, read_document, and read_implementation. Pull plus push or admin access is required for create, rename, archive, restore, start, and report lifecycle operations. Use an account with the required access or ask a repository owner to grant it.

Use the optional creating-chopin-plans skill to turn a settled coding-agent conversation into one initial document. The implementing-chopin-plans skill applies only after an implementation graph has been approved through a future or operator-provided approval path. Current MCP initialization instructions and tool descriptions override copied prompts or remembered command sequences.

References