suppa-mcp 1.0.26

MCP server for the Suppa platform (modern.suppa.me) — Tasks, Docs/Pages, Entities & Schema, Forms, and file attachments, with multi-tenant Google auth

Suppa 2.0 MCP Server

MCP (Model Context Protocol) server for the Suppa platform — provides AI agents with tools to manage Tasks, Docs/Pages, Entities & Schema, Forms, and file attachments.

Why MCP?

• API key stays local — never sent to the AI agent, stored only in .env
• Works with any MCP client — Claude Desktop, VS Code Copilot, Cursor, Windsurf, etc.
• No CORS/proxy issues — runs locally, makes direct HTTPS calls to Suppa
• 50+ tools covering Tasks, Documents, Entity schema, Forms, and 1.0→2.0 migration

Quick Start

1. Install

Recommended — zero-install via PyPI. Point your MCP client at uvx (uv); it fetches and runs the latest release on demand (the Python equivalent of npx), so there's nothing to install or update:

{ "mcpServers": { "suppa-2.0": { "command": "uvx", "args": ["--refresh", "suppa-mcp"] } } }

Or install the command explicitly:

uv tool install suppa-mcp       # or: pipx install suppa-mcp  /  pip install suppa-mcp

This provides a suppa-mcp command that any MCP client can launch directly.

From source instead:

# from a local clone
cd suppa2.0-mcp-server && pip install -e .

# or straight from the repository
pip install "git+https://git.modern-expo.com/asu/me-development/skills.git#subdirectory=suppa2.0-mcp-server"

2. Configure

cp .env.example .env
# Edit .env and set SUPPA_API_KEY

Then verify your token and connectivity without any client:

suppa-mcp --check
# OK: connected to https://modern.suppa.me — 139 entities visible.

3. Connect to your AI agent

Ready-to-copy configs are in examples/. Replace YOUR_TOKEN_HERE with your Suppa token. All clients use the same suppa-mcp command.

Claude Desktop — merge examples/claude_desktop_config.json into claude_desktop_config.json (Windows: %APPDATA%/Claude/, macOS: ~/Library/Application Support/Claude/):

{
  "mcpServers": {
    "suppa-2.0": {
      "command": "suppa-mcp",
      "env": {
        "SUPPA_API_KEY": "YOUR_TOKEN_HERE",
        "SUPPA_BASE_URL": "https://modern.suppa.me"
      }
    }
  }
}

VS Code Copilot — already wired in .vscode/mcp.json; it prompts for the token in a masked input. Start the suppa-2.0 server from the MCP view.

Cursor / Windsurf / Cline — use examples/cursor_mcp.json or examples/generic_mcp.json.

If a client reports suppa-mcp not found, its launcher can't see your Python Scripts dir on PATH. Use the explicit-interpreter fallback examples/claude_desktop_config.python-fallback.json (command = full path from where.exe python, args = ["-m","suppa_mcp"], cwd = this project).

Environment Variables

Variable	Default	Description
SUPPA_API_KEY	(required)	JWT token or API key
SUPPA_BASE_URL	https://modern.suppa.me	Platform URL
SUPPA_LANG	en	Language (en/uk)
SUPPA_TZ	Europe/Kyiv	Timezone
SUPPA_TASKS_ENTITY_ID	37	Entity ID for file uploads
SUPPA_HTTP_TIMEOUT	60	Per-request timeout, seconds
SUPPA_MCP_DEBUG	(off)	1 logs each request line to stderr

Prompts (guided workflows)

Clients that support MCP prompts (e.g. Claude Code slash commands) get three recipes:

Prompt	What it does
plan_my_day	Triage my overdue / due-today / active tasks into a prioritized plan
build_entity	Design-then-create an entity with fields, enums, and a generated form
migrate_from_v1	Safe 1.0 → 2.0 migration: dry-run → review plan → execute

Available Tools (59 total)

Tasks (16 tools)

Tool	Description
suppa_get_me	Current user profile
suppa_search_tasks	Search with filters (my, active, overdue, etc.)
suppa_count_tasks	Count matching tasks
suppa_get_task	Full task details
suppa_create_task	Create task
suppa_update_task	Update task fields
suppa_delete_task	Soft-delete task
suppa_move_task	Move to another stage
suppa_close_task	Close (completed stage)
suppa_add_comment	Comment with @mentions
suppa_get_comments	List task comments
suppa_attach_file	Upload & attach file
suppa_list_workflows	Available workflows
suppa_list_stages	Stages in a workflow
suppa_list_task_types	Task type options
suppa_search_users	Find users by name

Docs & Pages (13 tools)

Tool	Description
suppa_list_docs	List documents
suppa_get_doc	Document with page tree
suppa_create_doc	Create document
suppa_update_doc	Update document
suppa_delete_doc	Delete document
suppa_list_pages	Pages in a document
suppa_get_page	Page metadata
suppa_create_page	Create page
suppa_update_page	Update page
suppa_delete_page	Delete page
suppa_get_blocks	Raw block data
suppa_read_page	Readable text output
suppa_create_blocks	Add blocks to page
suppa_insert_block	Insert at position
suppa_update_block	Edit block content
suppa_delete_block	Remove block
suppa_reorder_blocks	Reorder blocks

Entity & Schema (12 tools)

Tool	Description
suppa_list_entities	All entities/tables
suppa_describe_entity	Full schema
suppa_search_records	Query any entity (paged: has_more/next_offset; match_any for OR filters)
suppa_get_record	Get one record by id
suppa_create_entity	Create new table
suppa_add_field	Add field to entity
suppa_add_enum_values	Add enum options
suppa_list_field_types	Available types
suppa_create_record	Insert record
suppa_update_record	Update record
suppa_delete_record	Delete record (instance)
suppa_attach_file_to_record	Attach a file to any entity record (auto-detects the file field)

Forms (6 tools)

Tool	Description
suppa_list_forms	List forms
suppa_get_form	Form with schema
suppa_create_form	Create form
suppa_update_form	Update form
suppa_generate_form_schema	Auto-generate from entity
suppa_add_field_to_form	Add field to form
suppa_list_form_field_types	Field type catalog

Migration

Tool	Description
suppa_migrate_entities_from_v1	Replicate Suppa 1.0 entities/fields into 2.0 (dry-run by default; supports reviewable plan files)

System

Tool	Description
suppa_health_check	Health check for stdio clients (config-only or deep connectivity check)

Authentication

The server authenticates with a single bearer token supplied via SUPPA_API_KEY:

• User JWT (account token, e.g. copied from the browser cookie accessToken) — full access to all domains including Tasks and the $current-user magic value.
• Integrator API key — works for Docs, Entities, Forms and Users. Task endpoints and $current-user may return empty results because they are scoped to a real user. Use a user JWT for Task workflows.

The token is read only from the environment, sent solely in the Authorization header to SUPPA_BASE_URL, and is never exposed to the AI agent.

Development

# Run directly (stdio)
python -m suppa_mcp

# Verify config + connectivity (no client needed)
python -m suppa_mcp --check

# Test with MCP inspector
mcp dev src/suppa_mcp/server.py

Auto-start Claude at login (stdio)

For Claude Desktop / VS Code, stdio is the preferred model: the MCP client spawns this server on demand and reconnects automatically.

To make startup reliable, install a login task that runs a preflight health check (suppa-mcp --check) and then starts Claude if it is not already running.

cd suppa2.0-mcp-server
./scripts/install-claude-startup.ps1 -Python C:\Python314\python.exe

The installed task (SuppaClaudeStartup) runs:

• scripts/start-claude-with-suppa.ps1 at user logon,
• connectivity check first (fails fast if token/config is invalid),
• Claude launch only when check passes.

Manage it:

Start-ScheduledTask -TaskName SuppaClaudeStartup
Get-ScheduledTask -TaskName SuppaClaudeStartup
./scripts/uninstall-claude-startup.ps1

Troubleshooting

mcp dev fails with spawn uv ENOENT — the MCP Inspector launches the server with uv. Install it and make sure it is on your PATH, then restart VS Code (so the new PATH is picked up):

python -m pip install uv
# add the user Scripts dir to PATH if `uv --version` is not found, e.g.
#   %APPDATA%\Python\Python3xx\Scripts

ModuleNotFoundError: No module named 'typing_extensions' (or suppa_mcp) when running mcp dev — you have multiple Python versions and the mcp launcher belongs to a different interpreter than the one where pip install -e . ran. Check with:

where.exe python   # interpreter that has suppa_mcp installed
where.exe mcp      # the CLI's interpreter — must be the same Python

Fix by using one interpreter, ideally a project virtual environment:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .
mcp dev src/suppa_mcp/server.py

You do not need uv or mcp dev for normal use — MCP clients (VS Code Copilot, Claude, Cursor) launch the server directly via python -m suppa_mcp, as configured in .vscode/mcp.json. The inspector is only a debugging tool.