README.md
Unofficial GitCafe Toolkit
Native GitCafe tools for Codex and other local MCP clients, using your existing
cafe auth login. Unofficial community integration; not affiliated with GitCafe.
Install in Codex
Requires Bun 1.2+ and @gitcafe/cli (tested with 0.10.0).
| 1 | bun install -g @gitcafe/cli |
| 2 | cafe auth login |
| 3 | git clone https://git.cafe/1gmedia/unofficial-toolkit-gitcafe.git |
| 4 | cd unofficial-toolkit-gitcafe |
| 5 | codex plugin marketplace add "$PWD" |
| 6 | codex plugin add unofficial-toolkit-gitcafe@gitcafe-toolkit |
The account owner completes CLI sign-in. If already signed in, reuse that login.
The launcher finds Bun and cafe on PATH or in ~/.bun/bin. No build is required
to use the plugin: server/dist/index.js includes the runtime dependencies.
Select Unofficial GitCafe Toolkit in a new Codex chat if the current chat
has not loaded its tools. Ask: “Show my GitCafe identity and list repositories
owned by 1gmedia.” Verify get_me returns the intended account.
The installed server is gitcafe_cli. It invokes the local CLI with structured
arguments and reuses that CLI's credentials. It does not request hosted MCP
OAuth, copy credentials, or send CLI tokens to the hosted MCP endpoint. Access
is governed by the existing CLI token. It targets https://git.cafe/api only.
Other clients
Claude Code
| 1 | /plugin marketplace add https://git.cafe/1gmedia/unofficial-toolkit-gitcafe.git |
| 2 | /plugin install unofficial-toolkit-gitcafe@unofficial-toolkit-gitcafe |
Or load a local clone for one session: claude --plugin-dir <path-to-clone>.
This existing Claude integration uses the hosted OAuth configuration in
examples/mcp-hosted-legacy.json. The skills appear as unofficial-toolkit-gitcafe:gitcafe-docs, :gitcafe-setup and
:gitcafe-safe-usage, and the gitcafe MCP server starts with the plugin; the first
call opens your browser to authorize it.
Claude Agent SDK
Point the SDK at a clone of this repo:
| 1 | import { query } from "@anthropic-ai/claude-agent-sdk"; |
| 2 | |
| 3 | for await (const message of query({ |
| 4 | prompt: "Open a stacked PR for my last two commits on git.cafe", |
| 5 | options: { plugins: [{ type: "local", path: "./unofficial-toolkit-gitcafe" }] }, |
| 6 | })) { |
| 7 | // ... |
| 8 | } |
| 1 | from claude_agent_sdk import ClaudeAgentOptions, query |
| 2 | |
| 3 | options = ClaudeAgentOptions( |
| 4 | plugins=[{"type": "local", "path": "./unofficial-toolkit-gitcafe"}], |
| 5 | ) |
In headless or CI runs the browser OAuth for the MCP server can't complete; rely
on the cafe CLI with CAFE_TOKEN set instead.
Grok
Add the ready-made git.cafe Agent bot template to your Grok, with the gitcafe skills built in.
Tools
| Capability | Native tools |
|---|---|
| Account and repositories | get_me, list_repositories, get_repository, list_branches |
| Source browsing | list_tree, read_file, search_code |
| Pull requests | list_pull_requests, get_pull_request, get_pull_request_diff, create_pull_request, comment_on_pull_request |
| Issues | list_issues, get_issue, create_issue, comment_on_issue |
Repository tools require an explicit owner/name. Lists default to 20 results,
with cursor pagination. PR creation requires explicit existing head/base branches
and defaults to draft. Write tools must follow the user's authorization. There
is no arbitrary shell, destructive admin, merge, push, or credential tool.
The adapter uses argument arrays without a shell, rejects invalid inputs, redacts credential fields, and limits each operation to 45 seconds and 2 MB of process output. Subprocess diagnostics never enter MCP stdout. After a timeout or uncertain write result, inspect GitCafe before retrying: a write may have completed. No automatic write retries are performed.
Optional hosted MCP
GitCafe also provides https://git.cafe/mcp, with a different tool set and its
own browser OAuth. An optional portable configuration is included at
examples/mcp-hosted.json. It is not enabled by default. Use your client's
remote MCP setup if you want that path; the account owner approves consent.
CLI/REST tokens and hosted MCP OAuth tokens are not interchangeable. The local adapter avoids reliance on the hosted consent UI by using the supported CLI. Hosted OAuth remains unverified in this installation because the repository selection controls did not respond in the tested browser sessions.
Codex 0.162.1 accepted automatic remote OAuth discovery but rejected explicit
per-server extensions.com.openai.auth metadata, so the optional example uses
only transport and URL. Plugin-owned servers may not appear in codex mcp list.
Skills and packaging
skills/gitcafe-docs/: concise references to official GitCafe documentation.skills/gitcafe-setup/: CLI sign-in, installation, and connection verification.skills/gitcafe-safe-usage/: optional guidance, explicitly opt-in in Codex.grok-skill/SKILL.md: standalone documentation skill for other agents.plugin.jsonandmcp.json: portable plugin format..codex-plugin/plugin.jsonand.mcp.json: compatibility metadata..agents/plugins/marketplace.json: local Codex marketplace registration..claude-plugin/: Claude Code and Claude Agent SDK marketplace and manifest..cursor-plugin/: Cursor plugin metadata and marketplace.
The CLI's seven embedded skills are not redistributed because its package is marked UNLICENSED. Install them from the CLI if needed:
| 1 | cafe skills install --global --target codex |
Other local MCP clients can run sh /absolute/path/to/server/start.sh.
A local subprocess requires Bun and the signed-in CLI on that machine; installing
this archive does not make the process available in a cloud harness.
Development and verification
| 1 | bun install --frozen-lockfile |
| 2 | bun test |
| 3 | bun run build |
| 4 | bun run test:live |
The live check exercises nine read tools through MCP stdio, including authenticated
identity, repository metadata, files, search, branches, PRs and issues. Set
GITCAFE_TEST_REPO=owner/repo to choose a different repository with a README.md.
It does not exercise write tools. Unit tests cover injection boundaries, draft
PR defaults, credential redaction, errors, timeouts and output limits.
After edits, rebuild the bundle, bump all plugin manifest versions consistently,
and rerun codex plugin add unofficial-toolkit-gitcafe@gitcafe-toolkit. Codex
loads an installed copy; source edits alone do not update it. Generated bundles
must retain server/THIRD_PARTY_NOTICES.txt.
GitCafe documentation references are a snapshot (CLI 0.10.0, October 2026). Consult official docs for current service behavior. See LICENSE and third-party notices.