StayFocus MCP server

Connect Claude, ChatGPT or any MCP client to your own StayFocus focus sessions, projects, experiments, notes and brain dump. OAuth 2.1, 15 tools, one endpoint.

Machine-readable copy of this page: /mcp.md

Summary

StayFocus is a focus-session app: you run one timed deep-work session at a time, park distracting thoughts in a brain dump, run two-week experiments, and keep a streak. The StayFocus MCP server lets an AI assistant read and write one authenticated user's own StayFocus data over the Model Context Protocol.

Every tool resolves the user from the authorizing token and scopes each query to that user. No tool can reach another user's data, billing data, or admin data.

Connection

Authentication

Two supported paths. Web connectors use OAuth; command-line clients that can set headers may use a bearer token instead.

Option A — OAuth 2.1 (Claude.ai, ChatGPT, any MCP web connector)

The user pastes only the endpoint URL. The client discovers and completes the flow automatically; no application registration with Anthropic or OpenAI is required.

GET  https://stayfocus.now/.well-known/oauth-protected-resource     # resource metadata
GET  https://stayfocus.now/.well-known/oauth-authorization-server   # authorization server metadata
POST https://stayfocus.now/oauth/register                           # dynamic client registration
GET  https://stayfocus.now/oauth/authorize                          # user approves the grant
POST https://stayfocus.now/oauth/token                              # authorization code + PKCE -> access token
POST https://stayfocus.now/mcp                                      # tool calls, Authorization: Bearer <token>

The issued token is bound to the user who approved the grant and carries the single scope mcp:use. The user can revoke it at any time in Settings → Account → AI assistant → Connected assistants.

Option B — bearer personal access token (desktop and CLI)

Generate a token in Settings → Account → AI assistant → Desktop & CLI (advanced). It is shown once. Send it on every request:

Authorization: Bearer <token>

Verify a token works:

curl -s -X POST https://stayfocus.now/mcp \
  -H "Authorization: Bearer $STAYFOCUS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Without a valid token the endpoint returns 401.

Client configuration

Claude.ai and Claude Desktop (web connector, OAuth)

1. Open claude.ai/settings/connectors → Add custom connector.

2. Name it StayFocus, paste https://stayfocus.now/mcp, confirm. There is no token field — none is needed.

3. Enable StayFocus from the search & tools menu in a chat.

4. On first use, approve the StayFocus grant screen. Claude Desktop and mobile sync the connector automatically.

Claude Code

# OAuth (recommended) — Claude Code opens the browser to authorize
claude mcp add --transport http stayfocus https://stayfocus.now/mcp

# Or with a personal access token
claude mcp add --transport http stayfocus https://stayfocus.now/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

Claude Desktop config file

Settings → Developer → Edit Config, then add:

{
    "mcpServers": {
        "stayfocus": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://stayfocus.now/mcp"
            ]
        }
    }
}

ChatGPT

1. Settings → Apps & Connectors, enable Developer mode (Plus, Pro, Team or Enterprise).

2. Create, name it StayFocus, paste https://stayfocus.now/mcp, choose OAuth as the authentication method.

3. Approve the StayFocus permission screen.

Any other MCP client

Point it at https://stayfocus.now/mcp with transport Streamable HTTP. Both OAuth and Authorization: Bearer are accepted.

Tools

15 tools — 7 read, 8 write. All parameters are JSON, passed as arguments to tools/call.

get-focus-sessions

Get the authenticated user's focus session history: total count, total focused minutes, and the most recent sessions.

Parameters: none.

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "get-focus-sessions"
    }
}

get-active-session

Get the authenticated user's currently running (or paused) focus session, if any.

Parameters: none.

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "get-active-session"
    }
}

get-projects

List the authenticated user's projects with status, visibility and description.

Parameters: none.

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "get-projects"
    }
}

create-project

Create a new project for the authenticated user. Projects are private by default.

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "create-project",
        "arguments": {
            "name": "…"
        }
    }
}

get-stats

Get the authenticated user's dashboard stats: streaks, total sessions, focused time and experiments summary.

Parameters: none.

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "get-stats"
    }
}

get-experiments

List the authenticated user's tiny experiments (time-bound commitments) and highlight the active one.

Parameters: none.

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "get-experiments"
    }
}

start-focus-session

Start a focus session on one of the user's projects. Idempotent: if a session is already running, it is returned unchanged instead of starting a new one.

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "start-focus-session",
        "arguments": {
            "project_uuid": "9f8c1e2a-7b4d-4c31-9a0e-5d6f7a8b9c0d",
            "intention": "…"
        }
    }
}

end-focus-session

End the user's running focus session. Safe: does nothing if no session is active.

Parameters: none.

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "end-focus-session"
    }
}

get-notes

Search and read the authenticated user's notes — their decision log, reflections and progress journal from the "Updates" page. Use this to answer questions like "what did I decide about X", "summarize my recent notes on project Y", or "search my notes for...". The user may ask in Arabic (e.g. "ملاحظاتي", "قراراتي", "مذكراتي") — treat that the same as "notes". Filter by free-text search, a project, or tags.

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "get-notes"
    }
}

create-note

Create a private note in the user's decision log / reflection journal (the "Updates" page). Use this when the user wants to record a decision, write down a reflection, log progress, or asks to "save this as a note" — including Arabic phrasing like "خليه كملاحظة" or "سجل هاد القرار". Optionally link the note to a project (get-projects for the uuid), tag it, and set a mood.

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "create-note",
        "arguments": {
            "content": "…"
        }
    }
}

get-brain-dump-items

List items in the user's brain dump — the capture lane for thoughts and ideas that are not a project, experiment or note yet. By default returns items that need attention: open items plus scheduled reminders that are now due. Use this to answer "what's in my brain dump?" / "شنو عندي فتفريغ الذهن دابا؟" or to check for reminders that just came due. Each item shows its uuid, content, status (open, scheduled, converted, archived) and whether a reminder is due.

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "get-brain-dump-items"
    }
}

capture-brain-dump-item

Capture a quick thought, idea or brain dump into the user's brain dump — for things that are not ready to become a project, experiment or note yet, or that should come back later. Use this whenever the user says things like "save this idea", "add this to my brain dump", "remind me about this later", or in Arabic "احفظ هاد الفكرة" / "خزن هاد الشي". Only the content is required — capture is zero-friction by design. The user can later ask to schedule a reminder, convert it to a project/experiment/note, or archive it.

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "capture-brain-dump-item",
        "arguments": {
            "content": "…"
        }
    }
}

schedule-brain-dump-reminder

Schedule (or reschedule) a reminder on an open brain dump item, so it resurfaces in "needs attention" later. Use this when the user says "remind me about this on Friday at 9am", "ذكرني بها يوم الجمعة" or similar. Get the item's uuid from get-brain-dump-items. Provide either "remind_at" with a concrete ISO 8601 date-time you computed from the user's request (must be in the future), or a "preset" (in_1_hour, tomorrow, next_week).

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "schedule-brain-dump-reminder",
        "arguments": {
            "item_uuid": "9f8c1e2a-7b4d-4c31-9a0e-5d6f7a8b9c0d"
        }
    }
}

archive-brain-dump-item

Archive an brain dump item once the user is done with it — it will no longer show up in "needs attention". Use this when the user says they're done with an idea, want to dismiss it, or "no longer need" something from their brain dump. Get the item's uuid from get-brain-dump-items.

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "archive-brain-dump-item",
        "arguments": {
            "item_uuid": "9f8c1e2a-7b4d-4c31-9a0e-5d6f7a8b9c0d"
        }
    }
}

convert-brain-dump-item

Turn a brain dump item into a project, a tiny experiment, or a reflection — when the user has decided what to do with a captured idea. Use this for requests like "turn this into a project" / "حولها لمشروع", "make this an experiment", or "save this as a reflection" / "احفظها كتأمل". Get the item's uuid from get-brain-dump-items. For "experiment", you may optionally pass duration_days, success_criteria and visibility.

Example call:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "convert-brain-dump-item",
        "arguments": {
            "item_uuid": "9f8c1e2a-7b4d-4c31-9a0e-5d6f7a8b9c0d",
            "target": "project"
        }
    }
}

Errors

Limits and rules

• Plan: the endpoint requires an active subscription or trial. Authentication succeeds but tool calls are refused without one.
• One active session: start-focus-session is a no-op when a session is already running; end it first with end-focus-session.
• Scope: every tool is scoped to the authorizing user. There is no way to read another user's data through this server.
• Write tools go through the same domain actions as the web app, so the same rules apply.
• Relative dates: the server does not parse "next Friday". Resolve dates to ISO 8601 before calling schedule-brain-dump-reminder.

Related

• Pricing — plans, limits and the free trial.
• StayFocus overview — what the product does.
• Sign up — create an account, then connect from Settings → Account.