Connect an MCP app#

Use GitCafe’s MCP endpoint to give an AI tool access to selected repositories. Each connection is limited to the repositories and permissions you approve. GitCafe does not verify third-party app names, so check the client ID and return host shown on the consent screen before continuing.

Read public repositories without signing in#

Add https://<your-gitcafe-host>/mcp to your MCP client without connecting an account. The server uses stateless Streamable HTTP, not WebSocket. Read tools then work on public repositories: code, refs, issues, pull requests, reviews and CI. list_repositories needs an owner or topic and cannot search by q. A private repository looks the same as one that does not exist.

File, tree and search tools take a branch or tag name such as main or v1.0, a full ref, an exact commit ID, or HEAD (the default). If a branch and a tag share a name, pass refs/heads/<name> or refs/tags/<name>. An oid argument pins the commit and takes precedence over ref.

Calling a write tool or get_me returns HTTP 401 with a sign-in challenge, and clients that support MCP authorization start the connection steps below. The challenge requests the read permissions plus only the permission that tool needs, such as issue write for create_issue. To read private repositories, connect first.

Connect a client#

You need a verified GitCafe account and access to at least one repository.

1. In your MCP client, add https://<your-gitcafe-host>/mcp as a remote MCP server. Use your GitCafe site’s real origin in place of the placeholder.
2. Follow the sign-in link opened by the client. The URL begins with /oauth/authorize on your GitCafe site.
3. Check the app name, client ID, and return host. Start again from your client if the request is missing or expired.
4. Select one or more repositories. Search and pagination do not change repositories you already selected. The app does not gain access to repositories created later. The screen shows the selection limit for the chosen permissions: at most 50 repositories and 100 repository-permission statements per connection. The default seven read permissions allow 14 repositories. Use separate connections for additional repositories.
5. Review permissions. Requested read access is included. Requested write or admin access starts turned off and is narrowed to read where that capability supports it. The screen uses the same repository, branch, issue, pull request, and comment permission descriptions as GitCafe access tokens.
6. Select Approve connection. GitCafe may ask you to confirm with a passkey or password, then returns you to the client.

Select Deny access to return without granting repository access. Never paste a token, password, or consent URL into a connector configuration; the browser flow handles authorization.

The connection can read your identity and its own approved repositories, permissions and expiry (the get_me tool); list and inspect approved repositories; read refs, trees, bounded files and literal code-search results; and list or read issues, pull requests, comments, reviews, commits, changed files, status and selected diffs when the approved permissions allow it. Optional write access can create or update issues, add or edit comments, create or update pull requests, submit reviews, resolve review threads, and merge pull requests. CI reads include commit checks and configured CI runs, jobs and shared logs. GitCafe applies the same permissions and version checks used by its API; approving a connection does not bypass repository rules. When a tool names a repository that does not exist or was not approved, the error says so without revealing which, and points the AI tool to get_me.

Review, merge and diagnose failures#

Ask your connected app to inspect a pull request, read selected diffs, and leave inline comments or replies. add_comment covers conversation comments, inline comments and replies; update_comment covers edits and thread resolution. Inline comments name an exact commit. Replies inherit the thread's anchor. Edits and resolution require the current comment version. Resolve or reopen a thread using its root comment ID. Thread resolution is local to GitCafe; it is not synchronized to GitHub. Comment reads support after pagination, and pull comment reads can filter general or inline comments.

To merge, explicitly approve the existing pr:merge:write permission during connection setup. An older connection without it needs new consent. Have the app read pull_request_read with facet: "status" for readiness, then call merge_pull_request with the reviewed head and base OIDs, current pull version, chosen strategy, and a stable requestId. Repository rules still apply.

A merge result of accepted means queued work, not a completed merge. Keep the returned operation ID and poll pull_request_read with facet: "merge_status" and operationId, waiting between polls. This read also requires merge permission. Wait for completed and its resulting commit OID; failed reports a terminal failure. Waiting or reconciliation results are not reasons to submit another merge. After a lost response, inspect current state before considering a retry; retain the original request ID and exact input.

Use ci_read to inspect runs, one run, commit checks, jobs, or a log. Runs, jobs and logs use the configured Buildkite integration; checks also include GitCafe and GitHub observations. Log access requires repository contents-read permission and owner-enabled log sharing. Log tails default to 16 KiB and are capped at 24 KiB. Returned byte offsets describe the original tail, not a pagination cursor. Check summaries and names may be shortened; truncatedFields identifies those fields. A truncated check list still reports the aggregate check state and counts. For run pages, pass next as after to continue.

MCP does not currently create branches or file commits, update a PR branch, dispatch/rerun/cancel CI, or administer/delete repositories. Use native Git or the supported CLI/provider workflow for those operations. Opening a pull request through MCP requires already-published branches.

Connection lifetime#

Access applies only to the repositories selected during approval. Reconnecting is required to add another repository or after the connection's 30-day lifetime or issuance limit. Access credentials are short-lived and refreshed by the client; a personal access token cannot be used in their place. Support for the MCP and OAuth protocols does not guarantee compatibility with every client or plan. The staging qualification record distinguishes tested client flows from protocol coverage.

Client-specific setup#

Claude#

In Claude, open Customize → Connectors → Add → Add custom connector. Enter a name and your GitCafe MCP URL. Continue with the detected Sign in now and Register automatically options, then select Add → Connect. Complete GitCafe consent and return to Claude's tool-permission settings. Leave tools set to Needs approval to review each call before it runs.

ChatGPT#

With developer mode available and enabled, open Plugins → Create app → Create MCP App. Enter a name and your GitCafe MCP URL, keep OAuth, acknowledge the custom-server warning, and select Create. ChatGPT discovers the OAuth endpoints and uses dynamic registration; no client secret is needed. Complete GitCafe consent, then open the installed app and select Try in chat.

Client menus and availability vary by plan and version. A client-side tool approval never expands the repositories or permissions approved in GitCafe.

Review or revoke access#

Open Settings → Authorized Apps to see each app’s exact repositories, permissions, credential refresh time, and expiration. The refresh time is not a log of individual tool calls. Select Revoke access, review the confirmation, and select Revoke app access. Revocation applies immediately; connect the app again if you need it later.

If an approval or revocation ends with a network error, do not repeatedly submit the action. Reload Authorized Apps to check the current server state first. For an expired consent request, return to the MCP client and begin a new connection. Revoking a connection invalidates its access immediately; a client must complete the browser approval flow again to reconnect.

Connect an API client#

OAuth clients that call GitCafe’s REST API use https://<your-gitcafe-host>/api as their OAuth resource (audience). This is API access, distinct from MCP access at /mcp; an access token for one resource cannot be used for the other. API OAuth covers only eligible repository REST operations authorized by the selected repositories and permissions. It does not grant organization, team, or profile access, and it does not issue Git or other user credentials. It cannot perform operations that require a browser session, including independent credential issuance. A signed-in browser session is not treated as an OAuth scoped grant.

Use the authorization-code flow with PKCE (S256). Include the exact /api resource parameter in both the authorization request and authorization-code token request. Keep using that resource when refreshing. A refresh request may narrow the permissions on its new access token. The replacement refresh token retains the prior refresh token's approved permission ceiling; reconnect and approve again to expand that ceiling.

Access tokens last at most 15 minutes. Each refresh returns a replacement refresh token that is valid for up to seven days, so a client left idle longer must reconnect. The connection ends after 30 days regardless. For the other ways to authenticate, see choose how to authenticate.

Cross-origin browser REST calls are supported only when they present a validated OAuth bearer token to an OAuth-enabled operation. Cookie-authenticated requests keep GitCafe's same-origin and CSRF protections and are not enabled for credentialed cross-origin use. GitCafe does not provide a compatibility resource or endpoint for the earlier staging shape.

To revoke a conventional OAuth access or refresh token, send both token and the connection’s client_id to the revocation endpoint. Token-only revocation is reserved for the auth.md flow below. The consent screen and Settings → Authorized Apps show the server-provided resource URL and label it API access or MCP access so you can confirm which audience the app requested.

Connect an agent using auth.md#

On instances that enable it, /auth.md describes the service_auth flow and links to authoritative OAuth discovery metadata. This flow grants API access, not MCP or native Git access. It does not create temporary accounts or repositories.

1. Give your agent the email address of your verified GitCafe account. The agent registers and shows a GitCafe verification link and six-digit code. Registration itself grants no access and sends no email.
2. Open the link, sign in with that account, and enter the code shown by your agent. Only continue if you asked the agent to connect. GitCafe may ask you to confirm your identity again.
3. Select existing repositories and permissions on the consent screen. Write and admin permissions start off. Approve or deny, then return to your agent.

The code expires after ten minutes and locks after five incorrect attempts. A mismatched or unverified email cannot confirm it. For an expired, locked, or lost request, ask the agent to register again rather than repeatedly submitting. Admission allows five registrations per email per hour and 100 per instance per hour; a rate_limited response requires waiting before trying again.

The approved connection and its assertion last at most one hour. Access tokens last at most 15 minutes. The agent reuses the signed assertion to obtain new tokens, with at most 100 issuances per registration; no refresh token is issued. Start again with new user consent after expiry. A connection cannot gain newly created repositories or issue independent credentials.

For auth.md tokens, posting token=<access_token>&token_type_hint=access_token to the advertised revocation endpoint revokes only that token. The assertion can still obtain another. To stop all access and further exchanges, revoke Agent registration (auth.md) in Settings → Authorized Apps.

Anonymous registration and provider-signed identity assertions are not supported. If /auth.md is unavailable or discovery omits agent_auth, use ordinary OAuth instead. Availability in source does not imply your instance has enabled it.