📋 mcp-server-smartsheet-rm

Enterprise Model Context Protocol (MCP) server for Resource Management by Smartsheet (10,000ft API).

Enables AI coding agents, planners, and assistants (Claude, Cortex, Antigravity, VS Code) to orchestrate the complete Smartsheet RM REST API surface: time tracking & timesheet reconciliation, resource scheduling & allocations, capacity planning, project & phase management, leaves/holidays, expense tracking, and custom fields.

🏗️ System Architecture

graph TD
    Client["AI Agent (Claude / Cortex / Antigravity / Cursor)"] -->|"MCP Stdio / Streamable HTTP /mcp"| Server["Root Gateway create_server()"]
    Server --> Middle["Parent Middleware (ParentAudit / ReadOnly Gate)"]
    Middle --> SubTime["time namespace (time_* — 15 tools, incl. 1 bulk-gated)"]
    Middle --> SubProj["projects namespace (projects_* — 25 tools, incl. 1 bulk-gated)"]
    Middle --> SubAdmin["admin namespace (admin_* — 60 tools)"]
    SubTime --> Guards["Domain Guards"]
    SubProj --> Guards
    SubAdmin --> Guards
    Guards --> ClientPool["SmartsheetRMClient (httpx.AsyncClient Pool)"]
    ClientPool -->|"Bearer Auth + 429 Jitter Retry"| API["Smartsheet RM (10,000ft API)"]

create_server mounts the time, projects, and admin sub-servers with FastMCP 4 namespace=, so tools/list names are time_*, projects_*, and admin_*. Legacy rm_* names are not registered on the gateway.

🚀 FastMCP 4 Server Composition

• Domain mounts (root.mount(..., namespace=...)):
  • namespace="time" → time_* (15 tools, including the bulk-gated time_bulk_delete_time_entries).
  • namespace="projects" → projects_* (25 tools, including the bulk-gated projects_bulk_delete_assignments).
  • namespace="admin" → admin_* (60 tools).
• Hierarchical middleware:
  • Parent: ParentAuditMiddleware (timing, lifecycle logs, secret redaction) and ReadOnlyGateMiddleware (annotation-driven read-only gate, see below).
  • Child: TimeDomainGuardMiddleware (logged hours must be 0–24; bulk gate), ProjectsDomainGuardMiddleware (project names must be non-empty; bulk gate), AdminDomainGuardMiddleware (per_page must be ≤ 1000).

Profiles

Pick a profile with --profile or SMARTSHEET_RM_PROFILE (default full). An unknown profile name fails at startup with ValueError. There are two kinds:

• Domain-mount profiles mount whole domains: full, time, projects, admin, and readonly.
• Job profiles mount every domain, then expose only an explicit list of tool names for one job. Prompts and resources stay available on every job profile and on readonly; the domain-mount profiles time, projects and admin carry only their own domain's prompts and resources. Each listed name is checked against the full catalog when the server builds, so a typo fails at startup.

Seven tools are in no job profile and are reachable only in full (or their domain-mount profile): time_bulk_delete_time_entries, projects_bulk_delete_assignments, admin_delete_client, admin_delete_client_contact, admin_create_expense_category, admin_delete_expense_category, and admin_delete_tag.

Read-only behavior

• The MCP readOnlyHint annotation is the only thing that decides whether a tool is read-only. Every tool declares it explicitly: true on the 39 reads and false on the 61 writes. A tool with no annotation or no readOnlyHint counts as a write.
• --profile readonly or SMARTSHEET_RM_READONLY=1 (on any profile) lists only the read-only tools, and ReadOnlyGateMiddleware refuses any call to a real tool that is not read-only, including a write the filter hid. A refusal comes back as a tool result with isError: true.
• A name that is not a tool on the server gets FastMCP's normal Unknown tool error, directly or through call_tool, so a typo is never reported as a blocked tool.
• With Tool Search on, the gate checks the tool that call_tool wraps. Reads through call_tool work and writes are refused. Without Tool Search, call_tool is not a tool on the server, so a call to it gets Unknown tool: 'call_tool'.
• If the gate cannot see the serving server, it refuses the call.

Bulk gate

time_bulk_delete_time_entries and projects_bulk_delete_assignments are listed in full, time and projects. The domain guards refuse them at call time (isError: true) unless SMARTSHEET_RM_ALLOW_BULK_DESTRUCTIVE=1, and the handlers still require confirm=True. Read-only mode hides and refuses them.

Tool Search and Code Mode

tools/list is flat by default. Discovery is opt-in and attaches only on full:

• --enable-tool-search / SMARTSHEET_RM_ENABLE_TOOL_SEARCH=1 replaces tools/list with search_tools and call_tool. The backend is regex (default) or bm25 (--tool-search-backend / SMARTSHEET_RM_TOOL_SEARCH_BACKEND).
• --enable-code-mode / SMARTSHEET_RM_ENABLE_CODE_MODE=1 attaches FastMCP's experimental Code Mode (search, get_schema, execute). It is skipped with a warning if the FastMCP build does not ship it.
• Turning on both raises ValueError. Asking for either on another profile logs a warning and keeps the flat list.
• search_tools, search and get_schema only read the catalog and are annotated readOnlyHint=True. Under read-only, Code Mode execute is refused.

⚡ Tool Surface Overview

The server exposes tools covering projects, resources, timesheets, and capacity. Call the namespaced names below:

• Default Registration: 100 tools on full (the 2 bulk-destructive tools are listed and refused at call time unless SMARTSHEET_RM_ALLOW_BULK_DESTRUCTIVE=1).
• Read-Only Mode: 39 tools (readOnlyHint=true).
• Destructive Gates: 21 tools requiring explicit confirm=True (19 standard + 2 bulk).
• Idempotent Operations: 43 tools with idempotentHint=true (the 39 read-only tools, plus time_update_time_approval_status, time_lock_timesheet, admin_set_custom_field_values, and admin_set_user_status).

Domain Overview

Agents call these tools/list names. Counts for time and projects include the bulk-gated tool.

1. Time (time_*, 15 tools): time_list_time_entries, time_get_time_entry, time_create_time_entry, time_update_time_entry, time_delete_time_entry, time_list_user_suggestions, time_update_time_approval_status, time_lock_timesheet, time_fill_weekly_timesheet, time_confirm_suggested_hours, time_reconcile_and_submit_week, time_list_approvals, time_create_approval, time_delete_approval. Bulk-gated: time_bulk_delete_time_entries.
2. Projects (projects_*, 25 tools): projects_list_projects, projects_get_project, projects_create_project, projects_update_project, projects_delete_project, projects_list_project_users, projects_list_project_phases, projects_get_project_phase, projects_create_project_phase, projects_update_project_phase, projects_delete_project_phase, projects_list_assignments, projects_get_assignment, projects_create_assignment, projects_update_assignment, projects_delete_assignment, projects_clone_project_schedule, projects_list_status_options, projects_list_placeholder_resources, projects_create_placeholder_resource, projects_delete_placeholder_resource, projects_list_assignment_subtasks, projects_create_assignment_subtask, projects_delete_assignment_subtask. Bulk-gated: projects_bulk_delete_assignments.
3. Admin (admin_*, 60 tools):
   • Users, roles, disciplines, and capacity: admin_list_users, admin_get_user, admin_create_user, admin_update_user, admin_delete_user, admin_list_user_bill_rates, admin_create_user_bill_rate, admin_get_user_availability, admin_get_user_utilization, admin_list_roles, admin_create_role, admin_update_role, admin_delete_role, admin_list_disciplines, admin_create_discipline, admin_update_discipline, admin_delete_discipline.
   • Clients and contacts: admin_list_clients, admin_get_client, admin_create_client, admin_update_client, admin_delete_client, admin_list_client_contacts, admin_create_client_contact, admin_delete_client_contact.
   • Leaves and holidays: admin_list_leave_types, admin_get_leave_type, admin_create_leave_type, admin_update_leave_type, admin_delete_leave_type, admin_list_holidays, admin_get_holiday, admin_create_holiday, admin_update_holiday, admin_delete_holiday.
   • Expenses: admin_list_expenses, admin_get_expense, admin_create_expense, admin_update_expense, admin_delete_expense, admin_list_expense_categories, admin_create_expense_category, admin_delete_expense_category.
   • Tags and custom fields: admin_list_tags, admin_create_tag, admin_delete_tag, admin_list_custom_fields, admin_get_custom_field, admin_create_custom_field, admin_update_custom_field, admin_delete_custom_field, admin_list_custom_field_values, admin_set_custom_field_values.
   • Status, reports, and webhooks: admin_get_user_statuses, admin_set_user_status, admin_get_report_rows, admin_get_report_totals, admin_list_webhooks, admin_create_webhook, admin_delete_webhook.

🚀 Quickstart & Installation

1. Run via uvx

Console scripts in [project.scripts] both call smartsheet_rm_mcp.server:main: smartsheet-rm-mcp (used below) and mcp-server-smartsheet-rm. Install examples stay unpinned. To freeze a release, pin the version from Releases.

uvx --from mcp-server-smartsheet-rm smartsheet-rm-mcp

After an upgrade, reload the MCP host so the live process start time is after the new binary mtime (stale process ≠ new package).

2. Installation

# Using uv (recommended)
uv pip install mcp-server-smartsheet-rm

# Or standard pip
pip install mcp-server-smartsheet-rm

3. Environment Variables

💻 Client Configurations

Google Antigravity (~/.gemini/antigravity-cli/mcp_config.json)

{
  "mcpServers": {
    "smartsheet-rm": {
      "command": "uvx",
      "args": ["--from", "mcp-server-smartsheet-rm", "smartsheet-rm-mcp"],
      "env": {
        "SMARTSHEET_RM_API_TOKEN": "your-api-token"
      },
      "lazy": true
    }
  }
}

Snowflake Cortex (~/.snowflake/cortex/mcp.json)

{
  "servers": {
    "smartsheet-rm": {
      "command": "uvx",
      "args": ["--from", "mcp-server-smartsheet-rm", "smartsheet-rm-mcp"],
      "env": {
        "SMARTSHEET_RM_API_TOKEN": "your-api-token"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "smartsheet-rm": {
      "command": "uvx",
      "args": ["--from", "mcp-server-smartsheet-rm", "smartsheet-rm-mcp"],
      "env": {
        "SMARTSHEET_RM_API_TOKEN": "your-api-token"
      }
    }
  }
}

Streamable HTTP

Prefer Streamable HTTP. --transport sse is deprecated (MCP spec SEP-2577); main() logs a migration warning and does not advertise /sse as the client path.

uvx --from mcp-server-smartsheet-rm smartsheet-rm-mcp --transport streamable-http --host 127.0.0.1 --port 8000

Connect clients to http://127.0.0.1:8000/mcp (FastMCP's default Streamable HTTP path). run(transport="streamable-http") does not set a custom path. Binding to 0.0.0.0 or :: requires an explicit --allowed-host (a wildcard * is rejected).

🛡️ Safety & Reliability

• Secret Redaction: API tokens, bearer headers, and sensitive keys are automatically scrubbed from errors and logs.
• Destructive Gates: Every deletion tool declares confirm: bool = False and rejects execution unless the caller explicitly passes confirm=True.
• Profiles: Minimize token footprint by loading only the tools one job needs (timesheets, staffing, org_setup, portfolio) or one domain (time, projects, admin).
• Read-Only Gate: readOnlyHint decides; anything else is refused with isError: true.
• Resilience: Exponential backoff with randomized jitter on HTTP 429 rate limits.

🧪 Testing & Validation

# Run tests with 100% coverage requirement
pytest --cov=src/smartsheet_rm_mcp --cov-fail-under=100 -v

# Run Tool Contract verification
python scripts/check_tool_contract.py

# Run OpenAPI Drift check
python scripts/check_openapi_drift.py