makiolaj/GearBox
1
0
Fork 0
Code Issues 8 Pull Requests Actions Packages Projects Releases 10 Wiki Activity

docs: add MCP OAuth documentation and fix lint

Browse Source 
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Jean-Luc Makiola
2026-04-04 09:27:34 +02:00
parent 6dcb421fb0
commit 5fdf4c3019
6 changed files with 51 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
CLAUDE.md
View File

@@ -102,10 +102,11 @@ curl -s -X POST "https://gitea.jeanlucmakiola.de/api/v1/repos/makiolaj/GearBox/a
- **Programmatic access**: API keys created in Settings > API Keys. Pass via `X-API-Key` header.
- **Public read**: All GET endpoints work without auth. POST/PUT/DELETE require auth.
- **Auth routes**: `/api/auth/login`, `/api/auth/logout`, `/api/auth/setup`, `/api/auth/me`, `/api/auth/password`, `/api/auth/keys`.
- **MCP OAuth**: OAuth 2.1 + PKCE for Claude mobile/web. Endpoints at `/oauth/*`. Uses existing GearBox credentials.
## MCP Server
GearBox includes a built-in MCP server for integration with Claude Code and Claude Desktop. Enabled by default, disable with `GEARBOX_MCP=false`. Authenticated via API key.
GearBox includes a built-in MCP server for integration with Claude Code and Claude Desktop. Enabled by default, disable with `GEARBOX_MCP=false`. Authenticated via API key or OAuth 2.1 Bearer token.
### Tools (19 total)
@@ -167,4 +168,23 @@ GearBox includes a built-in MCP server for integration with Claude Code and Clau
}
```
Generate an API key from Settings > API Keys after logging in.
Generate an API key from Settings > API Keys after logging in.
### OAuth Authentication (Claude Mobile / claude.ai)
GearBox supports OAuth 2.1 Authorization Code + PKCE for MCP connections from Claude mobile app and claude.ai. The OAuth flow is automatic — Claude handles discovery and token exchange.
**Required environment variable for production:**
```bash
GEARBOX_URL=https://your-gearbox-domain.com # Used as OAuth issuer URL
```
**OAuth endpoints:**
- `GET /.well-known/oauth-authorization-server` — Discovery metadata
- `POST /oauth/register` — Dynamic Client Registration
- `GET/POST /oauth/authorize` — Authorization with login form
- `POST /oauth/token` — Token exchange and refresh
**Both auth methods work simultaneously:**
- **API key** (`X-API-Key` header) — Claude Code, scripts, programmatic access
- **OAuth Bearer token** (`Authorization: Bearer` header) — Claude mobile, claude.ai