AegisGitea-MCP/docs/getting-started.md

Getting Started

Prerequisites

• Python 3.10 or higher
• A running Gitea instance
• A Gitea OAuth2 application for this MCP server
• make (optional but recommended)

1. Install

git clone <repo-url>
cd AegisGitea-MCP

# Install production dependencies
make install

# Or install with dev dependencies (for testing and linting)
make install-dev

To install manually without make:

python -m venv venv
source venv/bin/activate        # Linux/macOS
# or: venv\Scripts\activate     # Windows

pip install -e .
# dev: pip install -e ".[dev]"

2. Create a Gitea OAuth2 Application

1. In Gitea, open User Settings > Applications.
2. Create an OAuth2 application for AegisGitea-MCP.
3. Set the redirect URI to https://<host>/oauth/callback.
4. Copy the client ID and client secret.

3. Configure

Copy the example environment file and fill in your values:

cp .env.example .env

Minimum OAuth settings in .env:

GITEA_URL=https://gitea.example.com
OAUTH_MODE=true
GITEA_OAUTH_CLIENT_ID=<your-gitea-oauth-client-id>
GITEA_OAUTH_CLIENT_SECRET=<your-gitea-oauth-client-secret>
PUBLIC_BASE_URL=https://<host>
OAUTH_STATE_SECRET=<random-32-byte-minimum-secret>

GITEA_TOKEN is optional. If it is set, use a narrowly scoped service PAT and only grant it repository access you are prepared to expose after per-user authorization checks. If it is not set, Gitea REST calls use the authenticated user's OAuth token directly.

See Configuration for the full list of settings.

4. Optional Standard API Key Mode

For non-OAuth deployments, configure GITEA_TOKEN and MCP_API_KEYS. Generate an API key with:

make generate-key
# or: python scripts/generate_api_key.py

Copy the printed key into MCP_API_KEYS in your .env file and set OAUTH_MODE=false.

5. Run

make run
# or: python -m aegis_gitea_mcp.server

The server starts on http://127.0.0.1:8080 by default.

Verify it is running:

curl http://localhost:8080/health
# {"status": "healthy", ...}

6. Connect an AI Client

Claude

In claude.ai, open Settings > Connectors > Add custom connector and paste:

https://<host>/mcp

Claude discovers OAuth metadata, registers through /register, and uses PKCE S256 automatically.

Claude Code

claude mcp add --transport http aegis-gitea https://<host>/mcp

Claude Code uses the same remote MCP and OAuth metadata. Local development loopback callbacks are allowed by default.

Cowork

Cowork uses the same connector infrastructure and MCP URL as Claude.

SSE compatibility

If your client still expects SSE transport, use:

• SSE URL: https://<host>/mcp/sse
• Tool discovery URL: https://<host>/mcp/tools (no auth required)
• Tool call URL: https://<host>/mcp/tool/call

For a production deployment behind a reverse proxy, see Deployment.

Next Steps

• Configuration — tune file size limits, rate limiting, log paths
• API Reference — available tools and endpoints
• Security — understand authentication and audit logging
• Deployment — Docker and Traefik setup