Getting Started (end-to-end)

This is the full path from zero to a working MCP connection and your first tool call. No prior context assumed. Budget about five minutes.

0 · Prerequisites

You'll need

A DevFellowship account (you sign in with GitHub).
Node.js 20 or newer — only for the one-time login CLI. Check with node -v.
An MCP-compatible client: Claude Code, Cursor, VS Code, codex, or the Anthropic SDK. Any one is fine.

1 · Log in once with `dfl-auth`

The dfl-auth CLI runs the GitHub OAuth flow and stores your token locally. No install needed — npx fetches it on demand.

Configure the Supabase project (one time per machine):
Terminal window
```
npx @devfellowship/dfl-auth configure
```
Log in — this opens your browser for GitHub OAuth:
Terminal window
```
npx @devfellowship/dfl-auth login
```
Confirm you’re authenticated:
Terminal window
```
npx @devfellowship/dfl-auth status
```

Your credentials are written to ~/.dfl-mcp/:

File	Contents
`~/.dfl-mcp/project.json`	Supabase project configuration
`~/.dfl-mcp/credentials.json`	`access_token` + `refresh_token` + `expires_at`

Prefer a global install?

npm install -g @devfellowship/dfl-auth
dfl-auth login

2 · Pick your endpoints

The DFL MCP is split by domain. You add only the domains you need. The most common ones:

Domain	Endpoint	Use it for
work	`https://work.mcp.devfellowship.com/mcp`	projects, epics, deliveries, tasks, business units, placements
learn	`https://learn.mcp.devfellowship.com/mcp`	courses, lessons, members, profiles, progress
payments	`https://payments.mcp.devfellowship.com/mcp`	transactions, invoices

The full list is in the Tools reference. All endpoints share the same auth — only the tool set changes.

3 · Configure your client

Pick your client below. Replace YOUR_ACCESS_TOKEN with the token from step 1. Add or remove server blocks to match the endpoints you want.

Add to your project’s .mcp.json (or the global ~/.claude/mcp.json). One block per domain:

{
  "mcpServers": {
    "dfl-work": {
      "type": "http",
      "url": "https://work.mcp.devfellowship.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_ACCESS_TOKEN" }
    },
    "dfl-learn": {
      "type": "http",
      "url": "https://learn.mcp.devfellowship.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_ACCESS_TOKEN" }
    }
  }
}

Then restart Claude Code (or run /mcp to reconnect). You should see the dfl-work / dfl-learn tools appear.

Cursor needs mcp-remote as a proxy so the Authorization header is passed correctly. Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "dfl-work": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://work.mcp.devfellowship.com/mcp",
        "--transport", "http-only",
        "--header", "Authorization:${DFL_TOKEN}"
      ],
      "env": { "DFL_TOKEN": "Bearer YOUR_ACCESS_TOKEN" }
    }
  }
}

VS Code (1.102+) has native MCP support. Add to your workspace .vscode/mcp.json (or run MCP: Add Server from the command palette):

{
  "servers": {
    "dfl-work": {
      "type": "http",
      "url": "https://work.mcp.devfellowship.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_ACCESS_TOKEN" }
    }
  }
}

For older MCP extensions (e.g. Continue) that only speak SSE, use the mcp-remote proxy pattern shown in the Cursor tab.

Add each desired server to ~/.codex/config.toml:

[[mcp_servers]]
name = "dfl-work"
url = "https://work.mcp.devfellowship.com/mcp"
[mcp_servers.headers]
Authorization = "Bearer YOUR_ACCESS_TOKEN"

[[mcp_servers]]
name = "dfl-learn"
url = "https://learn.mcp.devfellowship.com/mcp"
[mcp_servers.headers]
Authorization = "Bearer YOUR_ACCESS_TOKEN"

Pass the endpoints in the mcp_servers array:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    mcp_servers=[
        {
            "type": "url",
            "url": "https://work.mcp.devfellowship.com/mcp",
            "name": "dfl-work",
            "authorization_token": "YOUR_ACCESS_TOKEN",
        },
    ],
    messages=[{"role": "user", "content": "Show me my open tasks"}],
)

4 · Make your first tool call

Once the client connects, just ask in natural language — the model picks the tool. Try:

“List my projects.” → calls list_projects on dfl-work

“What courses am I enrolled in?” → calls list_courses / list_members on dfl-learn

Want to verify the wiring without a client? Hit any endpoint directly:

# Health (no auth) — should return {"status":"ok", ...}
curl https://work.mcp.devfellowship.com/health

# Initialize a session (auth required)
curl -X POST https://work.mcp.devfellowship.com/mcp \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": { "name": "curl-test", "version": "1.0.0" }
    }
  }'

A 200 with a result means you’re connected. See the full per-domain tool list in the Tools reference.

5 · Troubleshooting

`401 Unauthorized`

Your token is missing, malformed, or expired.

Confirm the header format is exactly Authorization: Bearer <token> (one space).
Tokens expire — renew with the token refresh flow.

`403 Forbidden`

You’re authenticated, but your permissions don’t allow this. The MCP runs every call as you under Row-Level Security, so you only see/modify what your IAM role permits. This is expected, not a bug — see Auth & security.

Token refresh

Tokens are short-lived. Renew without re-running the browser login:

npx @devfellowship/dfl-auth refresh

import { getValidAccessToken } from '@devfellowship/dfl-auth';

// Reads ~/.dfl-mcp/credentials.json, auto-refreshes if expired.
const token = await getValidAccessToken();

Every endpoint exposes a refresh proxy (no auth header needed):

curl -X POST https://work.mcp.devfellowship.com/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "YOUR_REFRESH_TOKEN"}'

Allowlist / “endpoint not found”

Use the dotted host scheme: work.mcp.devfellowship.com, not the old mcp-work.devfellowship.com (which no longer resolves).
The tools path is always /mcp. /health is open; /mcp requires auth.

`npx` errors on Node v25

Clear the npx cache and retry:

rm -rf ~/.npm/_npx

Rate limited

Each endpoint rate-limits (~100 req/min by default). Back off and retry.

Next: Tools reference Every live per-domain endpoint and the tools it exposes, grouped by domain.