SmartSuite MCP Server

A locally-hosted Model Context Protocol (MCP) server that gives AI coding agents and desktop assistants governed, auditable access to SmartSuite data.

Works with Claude Desktop, Claude Code, Cursor, Cline, and any other MCP-compatible client.

---

What this is

The SmartSuite MCP server runs on your machine and communicates with your MCP client over stdio. It proxies requests to the SmartSuite REST API using your account credentials. The server enforces access modes, validates inputs, redacts secrets from logs, and writes local audit logs for all write operations.

---

Installation

Option 1: Claude Desktop extension (.mcpb)

Download the latest smartsuite-mcp-server-*.mcpb from the Releases page, then double-click to install in Claude Desktop. You'll be prompted for your account ID and API key. No Node.js required.

Option 2: npm (global)

npm install -g @smartsuite/mcp-server

Option 3: npx (no install)

npx @smartsuite/mcp-server

Option 4: Docker

docker pull smartsuite/mcp-server:latest

---

Quick start: Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "smartsuite": {
      "type": "stdio",
      "command": "smartsuite-mcp",
      "args": [],
      "env": {
        "SMARTSUITE_ACCOUNT_ID": "your-account-id",
        "SMARTSUITE_API_KEY": "your-api-key",
        "SMARTSUITE_BASE_URL": "https://app.smartsuite.com/api/v1",
        "SMARTSUITE_MCP_MODE": "readwrite"
      }
    }
  }
}

Restart Claude Desktop. You should see the SmartSuite tools in the connector panel.

---

Quick start: Claude Code

claude mcp add smartsuite \
  --env SMARTSUITE_ACCOUNT_ID=your-account-id \
  --env SMARTSUITE_API_KEY=your-api-key \
  --env SMARTSUITE_BASE_URL=https://app.smartsuite.com/api/v1 \
  --env SMARTSUITE_MCP_MODE=readwrite \
  -- smartsuite-mcp

---

Quick start: Docker

docker run --rm -i \
  -e SMARTSUITE_ACCOUNT_ID=your-account-id \
  -e SMARTSUITE_API_KEY=your-api-key \
  -e SMARTSUITE_MCP_MODE=readonly \
  smartsuite/mcp-server:latest

---

Access modes

| Mode | Read | Create/Update | Delete | Schema writes | |------|------|--------------|--------|---------------| | readonly | ✅ | ❌ | ❌ | ❌ | | readwrite | ✅ | ✅ | opt-in | opt-in | | admin | ✅ | ✅ | opt-in | opt-in |

Set with SMARTSUITE_MCP_MODE. Default is readonly.

---

Cross-workspace access

A SmartSuite API key can often reach several workspaces. By default this server is locked to the single workspace named in SMARTSUITE_ACCOUNT_ID (the "primary" workspace). Set SMARTSUITE_ENABLE_CROSS_WORKSPACE=true to let the server read from other workspaces the key can access.

When enabled:

• A new read-only tool smartsuite_list_workspaces lists the workspaces you can reach (slug, name, solution count, plan). It's hidden when the flag is off.
• Read tools gain an optional workspace parameter — pass a workspace slug or name to run that single call against a non-primary workspace. Omit it to use the primary.
• Cross-workspace access is read-only. Writes, updates, and deletes always target the primary workspace only; passing workspace to a write tool is rejected, regardless of access mode.
• Restrict the reachable set with SMARTSUITE_ALLOWED_WORKSPACES (comma-separated slugs or names). Empty means all workspaces the key can access. The primary is always allowed.

// Example: enable cross-workspace, limited to two workspaces
"env": {
  "SMARTSUITE_ENABLE_CROSS_WORKSPACE": "true",
  "SMARTSUITE_ALLOWED_WORKSPACES": "s36h7yr5,Reveal Risk"
}

// Then, in the client:
smartsuite_list_workspaces()                          → see what's reachable
smartsuite_list_solutions({ workspace: "Reveal Risk" })   → read another workspace by name
smartsuite_describe_application({ applicationId, workspace: "s36h7yr5" })  → by slug

---

Configuration

Required

| Variable | Description | |----------|-------------| | SMARTSUITE_ACCOUNT_ID | Your SmartSuite account ID | | SMARTSUITE_API_KEY | Your SmartSuite API key |

Optional

| Variable | Default | Description | |----------|---------|-------------| | SMARTSUITE_BASE_URL | https://app.smartsuite.com/api/v1 | API base URL | | SMARTSUITE_MCP_MODE | readonly | Access mode: readonly, readwrite, admin | | SMARTSUITE_MAX_RECORDS | 100 | Hard cap for list/query tools | | SMARTSUITE_MAX_BATCH_WRITES | 25 | Max records per batch create/update | | SMARTSUITE_ENABLE_DELETE | false | Enable delete tools | | SMARTSUITE_ENABLE_RESTORE | false | Enable restoring soft-deleted records from the trash | | SMARTSUITE_ENABLE_SCHEMA_WRITE | false | Enable schema write tools (create/update fields, formulas, forms, and automations) | | SMARTSUITE_ALLOWED_SOLUTIONS | (all) | Comma-separated solution IDs to allow. Enforced on every tool call (a tool targeting an application resolves the app's solution and is blocked if it's outside the list). list_solutions only returns allowed solutions, and list_applications only returns apps in them. | | SMARTSUITE_ALLOWED_APPLICATIONS | (all) | Comma-separated application IDs to allow. Enforced on every tool call. | | SMARTSUITE_DENIED_APPLICATIONS | (none) | Comma-separated application IDs to block. Always enforced. | | SMARTSUITE_ENABLE_CROSS_WORKSPACE | false | Allow read access to other workspaces your API key can reach (see Cross-workspace access) | | SMARTSUITE_ALLOWED_WORKSPACES | (all) | Comma-separated workspace slugs or names reachable when cross-workspace is enabled; empty allows all accessible workspaces | | SMARTSUITE_LOG_LEVEL | info | Log level: debug, info, warn, error | | SMARTSUITE_LOG_FILE | stderr | Path to write logs (default: stderr) | | SMARTSUITE_REQUEST_TIMEOUT_MS | 30000 | HTTP request timeout in milliseconds | | SMARTSUITE_RETRY_COUNT | 2 | Number of retries for rate limits and transient errors | | SCHEMA_CACHE_TTL_MS | 300000 | Application schema cache TTL (5 min) | | SMARTSUITE_AI_ENRICHED_RECORDS | false | Return field context (label, type, help text, linked field) with every record response | | SMARTSUITE_MIGRATION_DIR | (cwd) | Base directory for solution-migration project files (mappings/diff/xlsx, under .smartsuite-migrations/) |

Governance note: When a solution or application allowlist is set, enforcement is centralized — it applies to reads, writes, and config tools alike, and to tools identified only by a view/dashboard/widget id (their parent is resolved and checked). get_file_url (which takes an unscoped file handle) is disabled while an allowlist is active. For a locked-down deployment, also keep SMARTSUITE_ENABLE_CROSS_WORKSPACE=false — the allowlist scopes the primary workspace; cross-workspace and the migration/diff tools are a separate surface.

---

Tool list

Discovery & Schema

| Tool | Description | |------|-------------| | smartsuite_diagnostics | Validate configuration and connectivity | | smartsuite_list_workspaces | List workspaces your API key can access (only when cross-workspace is enabled) | | smartsuite_list_solutions | List accessible SmartSuite solutions | | smartsuite_get_solution | Get solution details | | smartsuite_list_applications | List applications; pass solutionId to filter to one solution. Use slim: true to inventory a whole solution cheaply (id, name, slug, solution, fieldCount); limit is enforced client-side | | smartsuite_describe_application | Application schema with field slugs, options, help text, and the record term. Pass includeLayout: true for record-view tabs, sections (collapse + visibility conditions), field rows, and field-level display logic | | smartsuite_create_application | readwrite + enable_schema_write | Create a table. Always sets a non-empty recordTerm (default "Record"). Pass fields: [{fieldType, label, params?}] to provision all of the table's fields in the same single request — the only true bulk field path SmartSuite offers, and far faster than adding them afterwards. Dry-run unless confirm:true | | smartsuite_update_application | readwrite + enable_schema_write | Rename a table (name) and/or change its recordTerm. Dry-run unless confirm:true | | smartsuite_list_fields | List fields for an application, with help text | | smartsuite_describe_field | Detailed field metadata: choice options, help text (+ format), linked-record targets and display format, formula expression + return type, record-title template, auto-number config, and native AI field config | | smartsuite_set_field_help_text | readwrite + enable_schema_write | Set/modify/clear a field's help text. Accepts markdown (paragraphs, bullet/ordered lists, bold/italic) → rich help_doc; displayFormat = tooltip or below_field_name. Applies asynchronously; dry-run unless confirm:true | | smartsuite_create_field | readwrite + enable_schema_write | Create a field of any type — incl. rollup ({linked_field, field_selection, function}) and lookup ({linked_field, field_selection}), not just formulas. Sparse params (SmartSuite fills defaults); choices for select/status (colors auto-assigned so dropdowns render right), linked_application+entries_allowed for linkedrecord (backlink auto-created). Slug generated, field placed in the layout. Dry-run unless confirm:true. (Formulas: use create_formula_field) | | smartsuite_create_fields | readwrite + enable_schema_write | Create many fields in one call — fields: [{fieldType, label, params?, aiPrompt?}]. SmartSuite has no bulk add-field API, so this is one request per field (~1s each), sequential on purpose (parallel adds get rate-limited and drop fields). Whole batch validated up front; a failure doesn't abort it — each field reports created + its error. For a new table, pass fields to create_application instead (all fields in a single request). Dry-run unless confirm:true | | smartsuite_update_field | readwrite + enable_schema_write | Update a field's label and/or params (shallow-merged patch; other params preserved; select choice colors auto-filled). Applies asynchronously; dry-run unless confirm:true | | smartsuite_delete_field | readwrite + enable_schema_write + enable_delete | Delete a field by slug (system fields refused). E.g. replace a formula with a rollup: create the rollup, delete the formula. Dry-run unless confirm:true |

Formulas

| Tool | Mode | Description | |------|------|-------------| | smartsuite_analyze_formulas | readonly | Review formula fields. Application-wide: every formula with return type, validity, native complexity score + tier, and structural metrics (function count, nesting depth, reference counts). Pass fieldSlug for one formula's dependency graph — reference chains resolved across linked records and compound sub-fields, rendered as an ASCII tree and a Mermaid flowchart. Add deep: true for the cross-table impact index (record count × link fan-out) | | smartsuite_validate_formula | readonly | Validate a formula expression against an application without writing anything. Returns {valid, safe, warnings} or the exact error (syntax, unknown function, missing field reference) | | smartsuite_create_formula_field | readwrite + enable_schema_write | Create a formula field. Validates the expression first (an invalid formula is never created); dry-run preview unless confirm: true | | smartsuite_update_formula_field | readwrite + enable_schema_write | Update a formula field's expression, label, and/or return type. Validates first; dry-run preview unless confirm: true |

Rec