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

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

Optional

Tool list

Discovery & Schema

Formulas

Records

Comments

Views & Dashboards

Forms

Automations

My Work

SmartDocs

Files

Security model

1. Credentials never reach the LLM. API key and account ID are loaded from environment variables and never included in tool responses or logs.
2. Secrets are redacted from all log output.
3. Access mode is enforced server-side. Write tools return a clear error in readonly mode.
4. Destructive operations require explicit opt-in (SMARTSUITE_ENABLE_DELETE=true) and a confirmation argument.
5. Batch writes require dry-run acknowledgement or confirm=true.
6. Application allowlists and denylists prevent access to sensitive tables.
7. Cross-workspace access is opt-in and read-only. Disabled by default; when enabled, other workspaces can be read but never written, and can be scoped with SMARTSUITE_ALLOWED_WORKSPACES.
8. All write operations write a local audit log (tool, account, application, record, timestamp, success/failure). Field values are not logged by default.

See SECURITY.md for the full security model.

Troubleshooting

"config error: Missing required environment variable"
Set SMARTSUITE_ACCOUNT_ID and SMARTSUITE_API_KEY in your MCP client config.

"SmartSuite API error 401"
Check that your API key is correct and not expired.

"This operation is blocked in readonly mode"
Set SMARTSUITE_MCP_MODE=readwrite to enable writes.

Tools not appearing in Claude Desktop
Restart Claude Desktop after updating the config file.

Logs polluting MCP output
Ensure SMARTSUITE_LOG_FILE is set to a file path, or that no other code writes to stdout. The server only writes JSON-RPC to stdout.

Development

# Install dependencies
npm install

# Type-check
npm run typecheck

# Build
npm run build

# Run tests
npm test

# Bundle single file for Docker/MCPB
npm run bundle

# Build and package the Claude Desktop extension (.mcpb)
npm run pack:mcpb
# Output: mcpb/smartsuite-mcp-server-<version>.mcpb

Project structure

src/
  index.ts              Entry point
  server.ts             MCP server bootstrap and tool dispatch
  config.ts             Environment variable loader
  logger.ts             Structured JSON logger (stderr or file)
  errors.ts             Error classes and codes
  auth.ts               SmartSuite auth header builder
  smartSuiteClient.ts   SmartSuite REST API client with schema cache
  workspaces.ts         Workspace resolver (slug/name → slug) and allowlist
  tools/
    registry.ts         Tool definitions (names, schemas, annotations)
    context.ts          Shared tool context type
    diagnostics.ts
    workspaces.ts
    solutions.ts
    applications.ts
    fields.ts
    formulas.ts        Formula analysis, validation, and field create/update
    forms.ts           Form review, create/update, and submit (form-type reports)
    mywork.ts          My Work — the authenticated user's assigned items
    records.read.ts
    records.write.ts
    files.ts
    comments.ts
    views.ts
    automations.ts     Automation review, usage/limits, and create/update/delete
    smartdocs.ts
  types/
    config.ts           Config interface
    smartsuite.ts       SmartSuite API types
  utils/
    audit.ts            Audit log writer
    pagination.ts       Cursor encode/decode
    prosemirror.ts      ProseMirror/SmartDoc → plain text
    redaction.ts        Secret redaction
    retry.ts            Exponential backoff retry
    safeJson.ts         Safe JSON stringify

License

MIT