MCP server

Connect AI agents directly to the gittan.eu API via Model Context Protocol.

The gittan.eu MCP server gives AI coding agents (Claude Code, Cursor, Windsurf, etc.) direct access to your gittan.eu organization — repos, pipelines, teams, secrets, and more — through the Model Context Protocol.

Instead of copying CLI output into chat, the agent calls gittan.eu tools natively: check pipeline status, list repos, read security findings, create teams, manage secrets.

Setup

Clone the MCP server and install dependencies:

git clone ssh://git@git.gittan.eu/bloomer/gittan-mcp.git
cd gittan-mcp
pnpm install

Make sure you're logged in to the gittan CLI — the MCP server shares the same credential store. No separate auth flow needed.

gittan auth login    # if not already logged in

Agent configuration

Add the server to your agent's MCP config. Set GITTAN_ORG to your org slug (shown in gittan status).

Claude Code

Add to .claude/settings.json in your project or ~/.claude/settings.json globally:

{
  "mcpServers": {
    "gittan": {
      "command": "npx",
      "args": ["tsx", "src/index.ts"],
      "cwd": "/path/to/gittan-mcp",
      "env": { "GITTAN_ORG": "your-org-slug" }
    }
  }
}

Cursor / Windsurf

Same structure in .cursor/mcp.json or .windsurf/mcp.json.

Available tools

34 tools across six areas:

Identity

Tool	Description
whoami	Current user's org memberships and roles

Organizations

Tool	Description
list_orgs	List organizations
dependency_graph	Cross-repo dependency graph
audit_log	Org audit log entries
list_deploy_hooks	Deploy hook configurations
list_service_accounts	Machine-to-machine accounts
list_policies	Pipeline policies
invite_user	Invite a user to the org
create_deploy_hook	Create a deploy hook

Teams

Tool	Description
list_teams	All teams in the org
get_team	Team details
list_members	Team members
team_metrics	DORA and team health metrics
team_activity	Recent team activity
create_team	Create a new team
add_team_member	Add member to team
remove_team_member	Remove member from team

Repositories

Tool	Description
list_repos	Repos in the org or filtered by team
get_repo	Repo details
list_branches	Branches in a repo
list_commits	Commit history
get_contents	File or directory contents
compare_commits	Diff between commits
create_repo	Create a new repo
delete_branch	Delete a branch
post_comment	Comment on a commit

Pipelines

Tool	Description
list_pipelines	Pipeline runs for a repo
get_pipeline_run	Details of a specific run
pipeline_status	Latest pipeline status for a repo
rerun_pipeline	Re-trigger a pipeline run

Secrets & security

Tool	Description
list_secrets	Secret names at org/team/repo scope
set_secret	Set a secret from a local source
delete_secret	Delete a secret
list_findings	Security scan findings

Security: secrets

The set_secret tool never accepts a secret value directly. Instead, it takes a source reference that tells the MCP server where to read the value locally:

// From an environment variable
set_secret({ scope: "repo", name: "DEPLOY_TOKEN", source: "env:DEPLOY_TOKEN" })

// From a file
set_secret({ scope: "team", name: "REGISTRY_TOKEN", source: "file:~/.secrets/registry" })

The value is read on the machine running the MCP server and sent directly to the gittan.eu API. It never passes through the AI agent's context, tool calls, or conversation history. Passing an inline value is rejected with an error.

Authentication

The MCP server uses your existing gittan CLI credentials — the same OIDC token stored by gittan auth login. No service account or separate configuration needed.

Token is auto-refreshed when it expires
If refresh fails, the server returns a clear error: "Run gittan auth login"
GITTAN_TOKEN env var overrides stored credentials
Client-side rate limiting: 60 requests/minute

Transport

The server uses stdio transport — it runs locally as a child process of your AI agent. No HTTP server, no open ports, no network exposure. The agent starts it, communicates via stdin/stdout, and the process exits when the session ends.