Skip to content
GitmoapdocsBeta
Concept· Why does it work like that?Draft

AI agents and the MCP server

Overview

Gitmoap runs an MCP server, so an AI assistant — Claude Code, Cursor, VS Code, or any client that speaks the Model Context Protocol — can read your repositories, work items, merge requests, specs and wikis on your behalf, and, if you let it, open and update work items and merge requests and comment on them. It sees and does exactly what the access token you give it allows, and nothing more.

The most useful thing it can read is a work item's Definition of Done. A work item's criteria are machine-checkable, so an agent can read what "done" means before it starts, and read them again afterwards to find out whether the work actually finished.

How it works

Connecting a client

The server is at /mcp on your Gitmoap API address, and there are two ways to connect.

By signing in. An app that supports signing in to MCP servers — claude.ai among them — needs only the address. It sends you to Gitmoap, you choose what to allow and what to limit it to, and it receives a token carrying exactly that, which it renews on its own. Connect an AI app by signing in walks through it.

With a token you mint. Any client can take an access token in the Authorization header, the same way a script does.

  1. Mint a personal access token with the mcp_agent bundle to read, or mcp_agent_write to read and write (see Access tokens). Bind it to one repository or group if the agent only needs that one — a bound token cannot read anything outside its binding, whatever it is asked.

  2. Add the server to your client with the token as a header. In Claude Code:

    shellscript
    claude mcp add --transport http gitmoap https://api.gitmoap.com/mcp \
    --header "Authorization: Bearer gmp_…"

    Cursor and VS Code take the same URL and header in their MCP settings.

Either way, what reaches the server is an access token. A sign-in session from the web app is not accepted on its own: a token carries exactly the scopes you chose, and a session carries everything you can do.

What an agent can do

ToolWhat it answers
gitmoap_whoamiWho the connection acts as, which scopes it has, and whether it is bound or read-only
gitmoap_resolveWhat an address or a pasted Gitmoap link names
gitmoap_searchWork items, merge requests, repositories, specs and wiki pages matching some text
gitmoap_repo_get, gitmoap_repo_listA repository, or the repositories in a group
gitmoap_code_read, gitmoap_code_grepA directory, a file or a line range at a ref, and text search over the files
gitmoap_commits_list, gitmoap_diff_get, gitmoap_refs_listHistory, what a change did, and branches, tags or releases
gitmoap_issue_search, gitmoap_issue_getWork items, and one work item with its criteria and whether each passes
gitmoap_code_anchorsWhich work items claim which code, and the TODO markers in it
gitmoap_mr_search, gitmoap_mr_getMerge requests, and one with everything that blocks it from merging
gitmoap_knowledge_find, gitmoap_knowledge_readA repository's specs and wiki pages
gitmoap_feedbackA short report to Gitmoap when the tools got in its way — see Feedback about Gitmoap

With a token that can write, it can also change things:

ToolWhat it changes
gitmoap_issue_create, gitmoap_issue_updateOpens a work item — or one from a TODO in the code — and edits, closes, reopens, labels, assigns, relates and plans it
gitmoap_issue_comment, gitmoap_issue_criteriaComments on a work item, and changes its Definition of Done
gitmoap_mr_create, gitmoap_mr_update, gitmoap_mr_commentOpens a merge request, edits, closes or reopens it and manages its reviewers, and comments on it — on one line of a file if it wants
gitmoap_mr_review, gitmoap_mr_mergeApproves or rejects, and merges. Each needs its own scope, which no bundle includes: you name it on the token if an agent should have it
gitmoap_branch_write, gitmoap_release_writeCreates or deletes a branch, and publishes or edits a release

A write tool lists only the actions your token can perform, so an agent is never offered something it would be refused.

Every tool takes and returns addresses rather than ids: acme/platform/api for a repository, acme/platform/api#412 for a work item, acme/platform/api!87 for a merge request, acme/platform/api@main:src/lib.rs#L10-L20 for lines of a file. A link copied from the web app works anywhere an address does.

Choosing what it sees

Add /readonly to the address — https://api.gitmoap.com/mcp/readonly — and the connection cannot change anything in your repositories, whatever the token allows: every tool that would is gone, and anything that tried anyway would be refused. Only gitmoap_feedback still works there, because it changes nothing of yours. Add /x/ and a list of toolsets — /mcp/x/repos,issues — to offer only those tools. The toolsets on by default are repos, issues, merge_requests and knowledge; the context tools are always there.

Three more are off unless you name them:

ToolsetToolsWhy it is off by default
pipelinesgitmoap_pipeline_runs, gitmoap_pipeline_logs, gitmoap_pipeline_triggerStarting a pipeline runs code with your namespace's secrets. Reading runs and logs is safe; the trigger needs pipeline:trigger, which no bundle includes
cataloggitmoap_service_get, gitmoap_service_list, gitmoap_insightsServices, deployments and the numbers about your work — useful, but not what most coding sessions need
admingitmoap_access_read, gitmoap_settings_get, gitmoap_audit_read, gitmoap_quota_readWho can reach what, what protects a branch, the audit log and your quota. Read-only: nothing on this surface changes anyone's access or weakens a rule

To add one to the defaults, name them all: /mcp/x/repos,issues,merge_requests,knowledge,pipelines.

Finding the server

An app that wants to know about the server before connecting can read its card at https://api.gitmoap.com/mcp/server-card: the server's name, its address, the protocol versions it speaks, and where to start signing in. It needs no credential, and it lists no tools — what an agent can do depends on its token, so only the server's tool list, asked with that token, can say.

What it writes, and how you can tell

Every description, comment and set of release notes an agent writes ends with a line such as via gitmoap MCP — Claude Code on behalf of @jane, so anyone reading it knows an agent wrote it and who it acted for. The change itself is made as you, under your token, and the audit log records it as yours along with the tool and the client.

A change that has started always finishes, even if the agent's client stops waiting, and the agent is told to look before trying again. Each token has a budget of tool calls per minute, weighted by what a tool costs — a merge counts more than a read — and an agent that runs through it is told how long to wait.

What it records

Every request an agent makes is recorded in the audit log like any other, along with the tool that made it and the name the client application gave itself — and, for an app you connected by signing in, the app you approved. One tool call can make several requests, and they share a request id, so you can see everything one call did.

Content you did not write

An agent reads work items, comments and code that other people wrote, and some of that text may try to give it instructions. The server strips hidden text and outside images before an agent sees them, and wraps anything written by someone who cannot push to the repository in a marker saying who wrote it.

Lockdown goes further. In a public repository — where anyone can write a comment — it withholds such text altogether, and refuses a work item or merge request opened by someone who cannot push. It is on whenever the token can change something, because that is when a misled agent could act on what it read; turn it off for a connection with the X-Gitmoap-MCP-Lockdown: false header when you need the agent to read those contributions.

The dependable protection is still the token: an agent cannot reach anything its token cannot. Give agents read-only connections where they only need to read, and tokens bound to the repository they work on.

Related