Grid Connect MCP Server

MCP server for Agentforce Grid (formerly AI Workbench). Enables Claude Code and other MCP clients to create, modify, and monitor Grid workbooks, worksheets, and columns through the Grid Connect API.

Highlights

• 10 consolidated MCP tools (down from 65) — less tool-selection overhead, faster LLM inference
• `apply_grid` — create an entire grid from a single YAML spec (one tool call replaces 10-15 sequential calls)
• Action-discriminated CRUD — workbook, worksheet, column, cell each handle all operations via an action parameter
• `discover` — single tool for all 25 metadata/data/agent discovery queries
• `column` — absorbs typed mutations (edit prompt, swap model, add evaluation) as flat parameters alongside raw config
• Composite workflows — setup_agent_test, poll_worksheet_status, get_worksheet_summary
• 20 model shorthands including GPT 5.1/5.2, Claude 4.5 Opus, Claude 4.6 Sonnet
• Hardened request logic with retry on network errors, 429 rate-limit respect, 5xx exponential backoff

Authentication

This server uses Salesforce CLI (sf) `api request` commands for all API calls. Authentication is handled entirely by the SF CLI:

• No manual token management required
• SF CLI handles OAuth flows, token refresh, and expiration automatically
• Supports all SF CLI authentication methods (web login, JWT, refresh tokens, etc.)
• Works with any org authenticated via sf org login

Quick Start

Prerequisites

Install Salesforce CLI:

brew install sf

Setup

1. Login to your Salesforce org:

sf org login web --alias my-org --instance-url https://your-instance.salesforce.com/

Or set as default org:

sf org login web --set-default --instance-url https://your-instance.salesforce.com/

1. Verify your connection:

Test that you can access the Grid Connect API:

sf api request rest "/services/data/v66.0/public/grid/workbooks" \
  --method GET \
  --target-org my-org

Or if you set a default org:

sf api request rest "/services/data/v66.0/public/grid/workbooks" \
  --method GET

1. Install and build:

npm install
npm run build

# Optional: Set environment variables if needed
# export ORG_ALIAS="orgfarm-org"  # If not set, uses SF CLI default org
# export INSTANCE_URL="https://your-instance.salesforce.com"  # Only for Lightning URL generation

npm start

Claude Code Configuration

Minimal configuration (uses SF CLI default org):

{
  "mcpServers": {
    "grid-connect": {
      "command": "node",
      "args": ["/path/to/agentforce-grid-mcp/dist/index.js"]
    }
  }
}

With specific org:

{
  "mcpServers": {
    "grid-connect": {
      "command": "node",
      "args": ["/path/to/agentforce-grid-mcp/dist/index.js"],
      "env": {
        "ORG_ALIAS": "orgfarm-org"
      }
    }
  }
}

Environment Variables

All environment variables are optional:

Architecture

src/
  index.ts                    # MCP server entry point
  client.ts                   # SF CLI API wrapper with retry logic
  schemas.ts                  # Zod schemas for all 12 column types
  types.ts                    # Shared types
  tools/
    workbook.ts               # 1 tool: workbook (6 actions: list, create, create_with_worksheet, get, get_worksheets, delete)
    worksheet.ts              # 1 tool: worksheet (11 actions: create, get, get_data, update, delete, add_rows, etc.)
    column.ts                 # 1 tool: column (15+ actions: CRUD + typed mutations like edit_ai_prompt, change_model)
    cell.ts                   # 1 tool: cell (5 actions: update, paste, trigger_execution, validate_formula, generate_ia_input)
    discover.ts               # 1 tool: discover (25 actions: all metadata, data, agent discovery)
    workflows.ts              # 3 tools: setup_agent_test, poll_worksheet_status, get_worksheet_summary
    apply-grid.ts             # 1 tool: apply_grid (YAML DSL → entire grid in one call)
    urls.ts                   # 1 tool: get_url (Lightning Experience URLs)
  lib/
    yaml-parser.ts            # Parse YAML DSL → GridSpec AST
    validator.ts              # 6-pass semantic validation (refs, cycles, types)
    config-expander.ts        # Flat YAML → triple-nested GCC JSON (Zod-validated)
    resolution-engine.ts      # Full pipeline: parse → validate → sort → create
    model-map.ts              # Model shorthand ↔ sfdc_ai__ ID mapping (20 shorthands)
    config-helpers.ts         # Shared: fetch config, resolve refs, deep merge
    column-config-cache.ts    # Session-lifetime config cache for typed mutations
    worksheet-data-helpers.ts # Helpers for columnData response format
    resource-cache.ts         # TTL-based cache for MCP resources

Tool Categories

apply_grid — Declarative Grid Creation

The flagship tool. Pass a YAML spec and get a complete grid:

workbook: Sales Agent Tests
worksheet: Q1 Regression
columns:
  - name: Utterances
    type: text

  - name: Agent Output
    type: agent_test
    agent: "Sales Coach"
    inputUtterance: "Utterances"

  - name: Coherence
    type: eval/coherence
    input: "Agent Output"

  - name: Topic Check
    type: eval/topic_assertion
    input: "Agent Output"
    reference: "Expected Topics"

data:
  Utterances:
    - "How do I reset my password?"
    - "What is my account balance?"

The tool handles:

• Workbook/worksheet creation
• Agent name → ID resolution
• Column dependency ordering (topological sort)
• Config expansion (flat YAML → nested JSON validated by Zod)
• Sequential column creation with ID wiring
• Data population
• dryRun mode for validation without API calls

Typed Mutation Tools

Modify existing grids without constructing raw JSON:

CRUD Tools

Standard operations for workbooks, worksheets, columns, cells, rows.

Discovery Tools

Composite Workflows

Column Types

All 12 Agentforce Grid column types are supported with typed Zod schemas:

Model Shorthands

Use short names instead of full sfdc_ai__* identifiers:

Validation

Every column config is validated against typed Zod schemas before hitting the API. The apply_grid tool adds 6-pass semantic validation:

1. Schema — required fields, valid types
2. Type-specific fields — each column type's required config
3. Reference integrity — all column name references resolve
4. Cycle detection — no circular dependencies (Kahn's algorithm)
5. Type compatibility — eval targets valid column types
6. Value validation — valid eval types, model names, response formats

Development

npm run build    # Compile TypeScript
npm run dev      # Watch mode
npm start        # Run the server