GGitea CGPT Connect Gitea
DOCUMENTATION

Connect AI to Gitea without giving it the keys to everything.

Gitea CGPT is a least-privilege MCP gateway for Gitea and Forgejo. You connect your instance, grant individual repositories, and decide separately whether each repository is read-only or writable.

Web apphttps://gitea-chat.kardos.dev
MCP endpointhttps://api.gitea-chat.kardos.dev/mcp
01 — QUICK START

Three boundaries before AI touches code.

  1. Connect a Gitea or Forgejo identity.Use a dedicated access token or supported Gitea OAuth connection.
  2. Grant repositories explicitly.A connected instance does not automatically expose its repositories to AI.
  3. Connect your MCP client.Use the production MCP endpoint. OAuth-capable clients can discover the authorization flow automatically.
02 — AUTHENTICATION

OAuth 2.1 for modern clients. Revocable tokens for everything else.

OAuth-capable MCP clients discover Gitea CGPT through protected-resource and authorization-server metadata. The flow uses authorization code + PKCE S256, short-lived access tokens and rotating refresh tokens.

Protected resource metadata https://api.gitea-chat.kardos.dev/.well-known/oauth-protected-resource

Manual MCP bearer tokens remain available in the dashboard for clients that do not support the OAuth flow. Gitea credentials themselves are never returned through MCP.

03 — OAUTH SCOPES

Read and write are separate permissions.

repo:read

List granted repositories, search paths, read files, branches and commit history.

repo:write

Create branches and commit bounded file changes. A paid plan and explicit repository write grant are still required.

usage:read

Read the current plan allowance and tool-call usage.

04 — MCP TOOLS

The AI surface is deliberately smaller than the Gitea API.

ToolModePurpose
list_repositoriesReadList only repositories explicitly granted to Gitea CGPT.
search_repositoryReadSearch repository file paths without dumping file contents.
read_fileReadRead one bounded file from a granted repository.
list_branchesReadInspect branches in a granted repository.
list_commitsReadInspect recent commit history.
get_usageReadCheck monthly allowance and current usage.
create_branchWriteCreate a branch from an existing branch.
write_fileWriteCreate or update one file and commit it.

Not exposed: repository deletion, force-push, organization administration, user administration, raw credential retrieval or arbitrary Gitea API proxying.

05 — SAFE WRITES

Prefer a branch before broad changes.

The intended AI workflow is: inspect the repository, search and read the relevant files, create a branch when practical, then make bounded file changes with explicit commit messages. Existing-file updates require the current file SHA, which protects against blind overwrites.

06 — LIMITS & AUDIT

Product limits are enforced server-side.

Tool calls are rate-limited and metered against the account plan. Repository grants, write permissions, plan entitlements and OAuth scopes are independent gates. Security-relevant activity is recorded in the account audit history.

Connect your Gitea