Documentation Index
Fetch the complete documentation index at: https://docs.driftless.icu/llms.txt
Use this file to discover all available pages before exploring further.
Driftless ships an MCP (Model Context Protocol) server that exposes your workspace context to AI clients. ChatGPT, Claude, Copilot, and any MCP-compatible client can read and write topics through it.
How it works
The MCP adapter runs at apps/mcp and translates MCP tool calls to the existing Driftless REST API. It is a protocol adapter only — it never accesses Postgres, internal libraries, or workspace admin operations directly.
AI Client (ChatGPT / Claude / Copilot)
│
▼ OAuth 2.0 bearer token
MCP Server (apps/mcp)
│
▼ REST API calls
Driftless API (apps/api)
│
▼
Postgres (Supabase)
| Tool | Description |
|---|
driftless_context_search | Full-text search across topics |
driftless_context_list | List topics with filters |
driftless_context_get | Retrieve a single topic by slug |
driftless_context_load_for_files | Match topics to file paths |
driftless_context_create | Create a new topic |
driftless_context_update | Update an existing topic (append-safe) |
driftless_context_diff | Get topics matching your local diff |
OAuth 2.0 setup
Third-party AI clients authorize through OAuth 2.0 with PKCE support.
For AI client developers
Register your client:
curl -X POST https://api.driftless.icu/api/v1/oauth/register \
-H "x-api-key: drift_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "My AI Client",
"redirect_uris": ["https://myapp.com/oauth/callback"],
"scopes": ["context:read", "topics:create", "topics:write"]
}'
OAuth scopes
| Scope | Description |
|---|
context:read | Read topics and context |
topics:create | Create new topics |
topics:write | Update existing topics |
context:diff | Read topic diff for local changes |
Authorization flow
- Redirect the user to
https://api.driftless.icu/api/v1/oauth/authorize?client_id=...&response_type=code&redirect_uri=...&scope=context:read+topics:write
- The user consents in the dashboard at
https://driftless.icu/oauth/authorize
- The dashboard redirects back to your
redirect_uri with an authorization code
- Exchange the code at
https://api.driftless.icu/api/v1/oauth/token for an access token
- Use the bearer token in MCP tool calls
Endpoints
| Method | Path | Purpose |
|---|
GET | /oauth/authorize | Authorization consent screen |
POST | /oauth/token | Exchange code for access token |
POST | /oauth/register | Register an OAuth client |
POST | /oauth/revoke | Revoke an access token |
Token security
- Authorization codes, access tokens, and refresh tokens are stored as hashes only — never plaintext
- Tokens are never logged or returned after initial issuance
- The MCP server does not import
@driftless/db, @driftless/scanner, typeorm, or any internal library — it calls the REST API exclusively
Connecting your AI client
Claude Desktop
Add this to your claude_desktop_config.json:
{
"mcpServers": {
"driftless": {
"url": "https://api.driftless.icu/mcp",
"headers": {
"Authorization": "Bearer drift_your_api_key_here"
}
}
}
}
ChatGPT / Copilot / other clients
Use the MCP endpoint URL directly:
https://api.driftless.icu/mcp
Bearer token in the Authorization header — either an API key (drift_...) for local/CI use, or an OAuth access token for published apps.
Local development
For local development, the MCP server runs on http://localhost:3020/mcp:
{
"mcpServers": {
"driftless": {
"url": "http://localhost:3020/mcp",
"headers": {
"Authorization": "Bearer drift_your_api_key_here"
}
}
}
}
Roadmap
| Feature | Status |
|---|
| MCP server with 7 context tools | Shipped (pending external review) |
| OAuth 2.0 authorize/token/register/revoke | Shipped (pending external review) |
Dashboard consent screen /oauth/authorize | Shipped (pending external review) |
| ChatGPT app submission | Pending |
| Claude integration testing | Pending |
pre_edit_check tool | Planned |
freshness tool | Planned |
suggest_topic tool | Planned |
