mcp-coda AGENTS.md

mcp-coda — Agent Context

MCP server for the Coda v1 API. 54 tools, 12 resources (2 data + 5 rules + 5 guides), and 5 prompts covering docs, pages, tables, rows, formulas, controls, permissions, folders, publishing, automations, and analytics.

Architecture

• Entry point: src/mcp_coda/__init__.py — click CLI, loads env, runs FastMCP server
• Client: src/mcp_coda/client.py — async httpx client with all Coda API methods
• Tools: src/mcp_coda/servers/ — modular tool files (one per domain: docs, pages, tables, rows, etc.)
• Helpers: src/mcp_coda/servers/_helpers.py — shared _get_client, _ok, _err, _check_write
• Resources: src/mcp_coda/servers/resources.py — MCP resources (static knowledge + live data)
• Prompts: src/mcp_coda/servers/prompts.py — MCP prompts (reusable task templates)
• Resource files: src/mcp_coda/resources/ — static markdown files for rules and guides
• Config: src/mcp_coda/config.py — CodaConfig dataclass from env vars
• Exceptions: src/mcp_coda/exceptions.py — CodaApiError, CodaNotFoundError, etc.
• Tests: tests/unit/ — 260+ tool-level unit tests

RBAC Model

1. Server-level: CODA_READ_ONLY=true blocks all write tools
2. MCP annotations: readOnlyHint, destructiveHint, idempotentHint per tool
3. Coda token scope: API token permissions enforce doc-level access

Key Patterns

• Tools never raise — all errors return _err(e) as JSON string
• Every tool returns str (JSON via _ok/_err)
• Write tools call _check_write(ctx) first
• List responses include {items, has_more, next_cursor, total_count}
• Rate limit errors include retry_after seconds
• Async mutations return requestId for polling via coda_get_mutation_status

MCP Compliance Rules

Tool Annotations (MANDATORY)

Every tool MUST have annotations={} with at minimum readOnlyHint and openWorldHint.

• Read tools: annotations={"openWorldHint": True, "readOnlyHint": True, "idempotentHint": True}
• Non-destructive write tools: annotations={"openWorldHint": True, "readOnlyHint": False}
• Destructive write tools: annotations={"openWorldHint": True, "destructiveHint": True, "readOnlyHint": False}
• Idempotent writes (PUT/update): add idempotentHint: True