# SmartSuite MCP Server - API Reference
## Overview
SmartSuite MCP Server exposes **7 MCP tools** for interacting with the SmartSuite API. All tools follow the Model Context Protocol (MCP) specification and include built-in safety features like dry-run mode and intelligent validation.
**Version**: 1.0.0
**Protocol**: MCP (Model Context Protocol)
**Base Architecture**: Entry Point → Server → Tools → Handlers → Client → SmartSuite API
---
## Table of Contents
1. [smartsuite_query](#1-smartsuite_query) - Query records
2. [smartsuite_record](#2-smartsuite_record) - Create/Update/Delete records
3. [smartsuite_schema](#3-smartsuite_schema) - Get table schema
4. [smartsuite_discover](#4-smartsuite_discover) - Discover tables and fields
5. [smartsuite_intelligent](#5-smartsuite_intelligent) - AI safety analysis
6. [smartsuite_field_create](#6-smartsuite_field_create) - Create fields
7. [smartsuite_field_update](#7-smartsuite_field_update) - Update fields
---
## 1. smartsuite_query
Query SmartSuite records with filtering, sorting, and pagination. Supports list, get, search, and count operations.
### Operations
- **list** - List records with optional filtering and pagination
- **get** - Get a single record by ID
- **search** - Search records with complex filters
- **count** - Count records matching filter criteria
### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `operation` | enum | ✅ Yes | - | Operation type: `list`, `get`, `search`, `count` |
| `tableId` | string | ✅ Yes | - | SmartSuite application ID (24-char hex) |
| `recordId` | string | Conditional | - | Record ID (required for `get` operation) |
| `limit` | number | No | 5 | Max records to return (1-1000). Default is 5 for MCP token optimization |
| `offset` | number | No | 0 | Starting offset for pagination |
| `filters` | object | No | - | Filtering criteria (MongoDB-style or structured format) |
### Examples
#### List Records
```json
{
"operation": "list",
"tableId": "68a8ff5237fde0bf797c05b3",
"limit": 10,
"offset": 0
}
```
#### Get Single Record
```json
{
"operation": "get",
"tableId": "68a8ff5237fde0bf797c05b3",
"recordId": "record-uuid-here"
}
```
#### Search with Filters
```json
{
"operation": "search",
"tableId": "68a8ff5237fde0bf797c05b3",
"filters": {
"operator": "and",
"fields": [
{"field": "status", "comparison": "is", "value": "active"},
{"field": "priority", "comparison": "is", "value": "high"}
]
},
"limit": 25
}
```
#### Count Records
```json
{
"operation": "count",
"tableId": "68a8ff5237fde0bf797c05b3",
"filters": {
"operator": "and",
"fields": [
{"field": "status", "comparison": "is", "value": "active"}
]
}
}
```
### Response Format
```json
{
"tool": "smartsuite_query",
"result": {
"items": [...],
"total": 100,
"offset": 0,
"limit": 5
},
"timestamp": "2025-11-11T09:00:00Z"
}
```
### Notes
- **Token Safety**: Default limit is 5 to prevent MCP context window explosion
- **Filter Operators**: Use correct operators for field types (see [Filtering Patterns](../config/knowledge/patterns/green/filtering.json))
- **Linked Records**: Use `has_any_of`/`has_all_of`/`has_none_of`, never `is` operator
---
## 2. smartsuite_record
Create, update, or delete SmartSuite records with DRY-RUN safety protection.
### Operations
- **create** - Create new record
- **update** - Update existing record
- **delete** - Delete record
### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `operation` | enum | ✅ Yes | - | Operation type: `create`, `update`, `delete` |
| `tableId` | string | ✅ Yes | - | SmartSuite application ID (24-char hex) |
| `recordId` | string | Conditional | - | Record ID (required for `update` and `delete`) |
| `data` | object | Conditional | - | Record data (required for `create` and `update`) |
| `dryRun` | boolean | No | `true` | Preview mode (prevents actual mutations) |
### Examples
#### Create Record (Dry Run)
```json
{
"operation": "create",
"tableId": "68a8ff5237fde0bf797c05b3",
"data": {
"title": "New Project",
"status": "active",
"priority": "high"
},
"dryRun": true
}
```
#### Update Record (Execute)
```json
{
"operation": "update",
"tableId": "68a8ff5237fde0bf797c05b3",
"recordId": "record-uuid-here",
"data": {
"status": "completed",
"completion_date": "2025-11-11"
},
"dryRun": false
}
```
#### Delete Record
```json
{
"operation": "delete",
"tableId": "68a8ff5237fde0bf797c05b3",
"recordId": "record-uuid-here",
"dryRun": false
}
```
### Response Format
```json
{
"tool": "smartsuite_record",
"result": {
"operation": "create",
"recordId": "new-record-uuid",
"dryRun": true,
"preview": {...}
},
"timestamp": "2025-11-11T09:00:00Z"
}
```
### Safety Features
- **Default Dry Run**: Always defaults to `dryRun: true` to prevent accidental mutations
- **Format Validation**: Validates field formats before submission (SmartDoc, linked records, etc.)
- **Field Translation**: Supports human-readable field names via field mappings
### Critical Field Formats
| Field Type | Format Requirement | Example |
|-----------|-------------------|---------|
| Linked Records | Array (even for single values) | `["uuid1", "uuid2"]` |
| Checklist | Full SmartDoc structure | See [CRITICAL-FORMATS-TRUTH.md](../coordination/smartsuite-truth/CRITICAL-FORMATS-TRUTH.md) |
| Status Fields | Option codes, not display labels | `"active"` not `"Active"` |
| Date Range | `{from_date, to_date}` structure | `{"from_date": "2025-01-01", "to_date": "2025-12-31"}` |
---
## 3. smartsuite_schema
Get SmartSuite table schema and field definitions with multiple output modes.
### Output Modes
- **summary** - Table info only (name, ID, record count)
- **fields** - Field names and types
- **detailed** - Full schema with metadata and field configurations
### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `tableId` | string | ✅ Yes | - | SmartSuite application ID (24-char hex) |
| `outputMode` | enum | No | `summary` | Output detail level: `summary`, `fields`, `detailed` |
### Examples
#### Get Summary
```json
{
"tableId": "68a8ff5237fde0bf797c05b3",
"outputMode": "summary"
}
```
#### Get Fields List
```json
{
"tableId": "68a8ff5237fde0bf797c05b3",
"outputMode": "fields"
}
```
#### Get Full Schema
```json
{
"tableId": "68a8ff5237fde0bf797c05b3",
"outputMode": "detailed"
}
```
### Response Format
```json
{
"tool": "smartsuite_schema",
"result": {
"name": "Projects",
"id": "68a8ff5237fde0bf797c05b3",
"fields": [
{
"label": "Project Name",
"slug": "project_name",
"field_type": "textfield"
}
]
},
"timestamp": "2025-11-11T09:00:00Z"
}
```
### Performance
- **Caching**: Schema responses are cached with LRU strategy
- **Token Optimization**: Use `summary` mode to minimize MCP token usage
---
## 4. smartsuite_discover
Discover available tables and explore field mappings. Essential for navigating cryptic field IDs.
### Operations
- **tables** - List all accessible tables in workspace
- **fields** - List field mappings for specific table
### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `operation` | enum | ✅ Yes | - | Discovery type: `tables` or `fields` |
| `tableId` | string | Conditional | - | Table name or ID (required for `fields` operation) |
### Examples
#### Discover Tables
```json
{
"operation": "tables"
}
```
#### Discover Field Mappings
```json
{
"operation": "fields",
"tableId": "68a8ff5237fde0bf797c05b3"
}
```
### Response Format
```json
{
"tool": "smartsuite_discover",
"result": {
"tables": [
{
"id": "68a8ff5237fde0bf797c05b3",
"name": "Projects",
"structure": "projects"
}
]
},
"timestamp": "2025-11-11T09:00:00Z"
}
```
### Use Cases
- Initial workspace exploration
- Finding table IDs for API calls
- Mapping human-readable names to SmartSuite field IDs
- Understanding available fields before record operations
---
## 5. smartsuite_intelligent
AI-guided safety analysis for SmartSuite operations. Analyzes requests against knowledge base to detect dangerous patterns.
### Modes
- **learn** - Basic pattern analysis
- **dry_run** - Detailed validation with warnings
- **execute** - Comprehensive analysis with execution recommendations
### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `endpoint` | string | ✅ Yes | - | SmartSuite API endpoint (e.g., `/applications/{id}/records/list/`) |
| `method` | enum | ✅ Yes | - | HTTP method: `GET`, `POST`, `PUT`, `DELETE`, `PATCH` |
| `operationDescription` | string | ✅ Yes | - | Human-readable description of intended operation |
| `mode` | enum | No | `learn` | Analysis depth: `learn`, `dry_run`, `execute` |
| `tableId` | string | No | - | Table ID for context-aware analysis |
| `payload` | object | No | - | Request payload to validate |
### Examples
#### Analyze Field Update
```json
{
"endpoint": "/applications/68a8ff5237fde0bf797c05b3/fields/sf123abc/",
"method": "PATCH",
"operationDescription": "Update status field choices",
"mode": "dry_run",
"payload": {
"params": {
"choices": [
{"value": "active", "label": "Active"},
{"value": "inactive", "label": "Inactive"}
]
}
}
}
```
#### Check Filtering Operation
```json
{
"endpoint": "/applications/68a8ff5237fde0bf797c05b3/records/list/",
"method": "POST",
"operationDescription": "Search for active projects",
"mode": "learn",
"payload": {
"filter": {
"operator": "and",
"fields": [
{"field": "status", "comparison": "is", "value": "active"}
]
}
}
}
```
### Response Format
```json
{
"tool": "smartsuite_intelligent",
"result": {
"safetyLevel": "GREEN",
"analysis": {
"warnings": [],
"blockers": [],
"recommendations": ["Operation appears safe to execute"]
},
"matchedPatterns": ["GREEN_003: Record Operations - Fully Functional"],
"knowledgeBaseVersion": "2.0.0"
},
"timestamp": "2025-11-11T09:00:00Z"
}
```
### Safety Levels
| Level | Meaning | Action |
|-------|---------|--------|
| 🟢 **GREEN** | Safe operation | Proceed with confidence |
| 🟡 **YELLOW** | Caution required | Review warnings before proceeding |
| 🔴 **RED** | Dangerous pattern detected | DO NOT EXECUTE - fix issues first |
### Known Patterns
- **RED Patterns**: UUID corruption, wrong filter operators, format errors
- **YELLOW Patterns**: Bulk limits, token explosion, rate limiting, field positioning
- **GREEN Patterns**: Field creation, record CRUD, filtering, bulk operations
### Important Notes
- **Analysis Only**: This tool performs analysis - use `smartsuite_query` or `smartsuite_record` for actual execution
- **Knowledge Base**: Patterns loaded from `config/knowledge/` at startup
- **Pattern Citations**: All warnings include pattern ID and reference documentation
---
## 6. smartsuite_field_create
Create new fields in SmartSuite tables with format validation and UUID corruption prevention.
### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `tableId` | string | ✅ Yes | - | SmartSuite application ID (24-char hex) |
| `fieldConfig` | object | ✅ Yes | - | Field configuration (see below) |
| `dryRun` | boolean | No | `true` | Preview mode (prevents schema changes) |
### Field Configuration
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `field_type` | string | ✅ Yes | Field type (e.g., `textfield`, `numberfield`, `singleselectfield`) |
| `label` | string | ✅ Yes | Field display label |
| `slug` | string | ✅ Yes | Field slug (unique identifier) |
| `params` | object | No | Field-specific parameters (use `choices` not `options` for select fields) |
### Examples
#### Create Text Field
```json
{
"tableId": "68a8ff5237fde0bf797c05b3",
"fieldConfig": {
"field_type": "textfield",
"label": "Project Code",
"slug": "project_code"
},
"dryRun": true
}
```
#### Create Select Field
```json
{
"tableId": "68a8ff5237fde0bf797c05b3",
"fieldConfig": {
"field_type": "singleselectfield",
"label": "Priority",
"slug": "priority",
"params": {
"choices": [
{"value": "low", "label": "Low"},
{"value": "medium", "label": "Medium"},
{"value": "high", "label": "High"}
]
}
},
"dryRun": false
}
```
### Supported Field Types
- `textfield` - Single line text
- `textareafield` - Multi-line text
- `numberfield` - Numeric values
- `singleselectfield` - Single choice from list
- `multiselectfield` - Multiple choices from list
- `datefield` - Date picker
- `checkboxfield` - Boolean checkbox
- `linkedrecordfield` - Links to other records
- And more (see SmartSuite documentation)
### Critical Warnings
- **Use "choices" not "options"**: For select fields, always use `params.choices` not `params.options` to prevent UUID corruption (Pattern RED_006)
- **Slug Uniqueness**: Slugs must be unique within the table
- **Default Dry Run**: Always test with `dryRun: true` first
---
## 7. smartsuite_field_update
Update existing fields in SmartSuite tables. Critical for maintaining schema integrity.
### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `tableId` | string | ✅ Yes | - | SmartSuite application ID (24-char hex) |
| `fieldId` | string | ✅ Yes | - | Field ID to update |
| `updates` | object | ✅ Yes | - | Field updates (partial updates supported) |
| `dryRun` | boolean | No | `true` | Preview mode (prevents schema changes) |
### Examples
#### Update Field Label
```json
{
"tableId": "68a8ff5237fde0bf797c05b3",
"fieldId": "sf123abc",
"updates": {
"label": "Updated Project Name"
},
"dryRun": true
}
```
#### Update Select Field Choices
```json
{
"tableId": "68a8ff5237fde0bf797c05b3",
"fieldId": "sf456def",
"updates": {
"params": {
"choices": [
{"value": "active", "label": "Active", "color": "#00FF00"},
{"value": "inactive", "label": "Inactive", "color": "#FF0000"}
]
}
},
"dryRun": false
}
```
### Critical Warnings
- **UUID Preservation**: When updating select field choices, ALWAYS include existing choice UUIDs to prevent data corruption (Pattern RED_006)
- **Complete Choices Array**: Provide the FULL choices array, not just the changes you want to make
- **Use "choices" not "options"**: Same as field creation - use `params.choices` not `params.options`
### Dangerous Anti-Pattern
```json
// ❌ WRONG - Will corrupt existing choice UUIDs
{
"updates": {
"params": {
"choices": [
{"value": "new_status", "label": "New Status"} // Missing existing choices!
]
}
}
}
```
### Safe Pattern
```json
// ✅ CORRECT - Preserves existing UUIDs
{
"updates": {
"params": {
"choices": [
{"value": "active", "label": "Active", "id": "existing-uuid-1"},
{"value": "inactive", "label": "Inactive", "id": "existing-uuid-2"},
{"value": "new_status", "label": "New Status"} // Only new choice lacks UUID
]
}
}
}
```
---
## Common Patterns & Best Practices
### 1. Always Use Dry Run First
```json
// Step 1: Preview the operation
{"operation": "update", "dryRun": true, ...}
// Step 2: Review the preview output
// Step 3: Execute if safe
{"operation": "update", "dryRun": false, ...}
```
### 2. Filter Pattern (Structured Format)
```json
{
"filters": {
"operator": "and", // or "or"
"fields": [
{"field": "status", "comparison": "is", "value": "active"},
{"field": "project_id", "comparison": "has_any_of", "value": ["uuid1", "uuid2"]}
]
}
}
```
### 3. Pagination Pattern
```json
{
"operation": "list",
"tableId": "...",
"limit": 25,
"offset": 0 // First page: offset=0, Second page: offset=25, etc.
}
```
### 4. Error Handling
All tools return consistent error format:
```json
{
"error": "ValidationError",
"message": "Invalid tableId format: must be 24-character hex string",
"code": "INVALID_TABLE_ID"
}
```
---
## Rate Limiting & Performance
### SmartSuite API Limits
- **Rate Limit**: 5 requests per second (enforced by SmartSuite)
- **Bulk Operations**: Max 100 records per bulk operation
- **Response Size**: Large responses may hit API timeout (30s)
### MCP Token Optimization
- **Default Limit**: Query operations default to `limit: 5` to prevent context explosion
- **Schema Caching**: Schema responses cached to reduce API calls
- **Output Modes**: Use `summary` mode to minimize token usage
### Performance Tips
1. Use `count` operation before large list operations
2. Implement pagination for large datasets
3. Cache schema responses in your application
4. Use field discovery once, then cache field mappings
5. Batch related operations when possible
---
## Environment Configuration
### Required Variables
```bash
SMARTSUITE_API_KEY=your-api-token-here
SMARTSUITE_WORKSPACE_ID=your-workspace-id
```
### Optional Variables
```bash
SMARTSUITE_API_URL=https://app.smartsuite.com/api/v1 # Default
SMARTSUITE_DRY_RUN=true # Force dry run for all mutations
DEBUG=true # Enable debug logging
LOG_LEVEL=info # error, warn, info, debug
```
---
## Testing & Validation
### Test Workspace
Use a dedicated test workspace for development:
```bash
SMARTSUITE_WORKSPACE_ID=your-test-workspace-id
```
### Validation Mode
Run server in validation mode (starts then exits):
```bash
MCP_VALIDATE_AND_EXIT=true npm start
```
### Quality Gates
```bash
npm run lint # ESLint checks
npm run typecheck # TypeScript validation
npm run test # Run test suite
```
---
## Support & Resources
- **Architecture**: [docs/001-ARCHITECTURE.md](./001-ARCHITECTURE.md)
- **Deployment**: [docs/DEPLOYMENT.md](./DEPLOYMENT.md)
- **Troubleshooting**: [docs/TROUBLESHOOTING.md](./TROUBLESHOOTING.md)
- **Contributing**: [docs/CONTRIBUTING.md](./CONTRIBUTING.md)
- **Knowledge Base**: [config/knowledge/](../config/knowledge/)
---
**Version**: 1.0.0
**Last Updated**: 2025-11-11
**License**: MIT
