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: ``bash brew install sf ``

Setup

Login to your Salesforce org:

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

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

Verify your connection:

Test that you can access the Grid Connect API: ``bash sf api request rest "/services/data/v66.0/public/grid/workbooks" \ --method GET \ --target-org my-org ``

Or if you set a default org: ``bash sf api request rest "/services/data/v66.0/public/grid/workbooks" \ --method GET ``

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:

| Variable | Default | Description | |----------|---------|-------------| | ORG_ALIAS | SF CLI default org | Target org alias (if not set, SF CLI uses your default org) | | INSTANCE_URL | undefined | Salesforce instance URL (required only for Lightning Experience URL generation via get_url tool) | | API_VERSION | v66.0 | Salesforce API version | | GRID_TIMEOUT | 60000 | Request timeout in milliseconds | | GRID_DEBUG | false | Enable debug logging to stderr |

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:

| Tool | Purpose | |------|---------| | edit_ai_prompt | Change instruction, model, response format on AI columns | | edit_agent_config | Update agent, utterance, context variables | | add_evaluation | Add evaluation column with auto-wired references | | change_model | Switch LLM model (supports shorthands like gpt-4-omni, claude-4.5-sonnet) | | update_filters | Change Object/DataModelObject query filters | | reprocess | Reprocess column or worksheet (all/failed/stale) | | edit_prompt_template | Update template and input mappings |

CRUD Tools

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

Discovery Tools

| Tool | Returns | |------|---------| | get_agents | Available agents with IDs, versions, topics | | get_llm_models | Available models | | get_evaluation_types | All 12 evaluation types | | get_sobjects / get_sobject_fields | SObject metadata | | get_dataspaces / get_data_model_objects | Data Cloud DMOs | | get_prompt_templates | Available prompt templates | | get_invocable_actions | Available Flows, Apex, etc. | | get_formula_functions / get_formula_operators | Formula reference |

Composite Workflows

| Tool | Purpose | |------|---------| | setup_agent_test | Create a full agent test suite in one call | | poll_worksheet_status | Poll until processing completes | | get_worksheet_summary | Structured column/status summary | | create_workbook_with_worksheet | Create both in one step |

Column Types

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

| Type | DSL Name | Purpose | |------|----------|---------| | AI | ai | LLM text generation with custom prompts | | Agent | agent | Run agent conversations | | AgentTest | agent_test | Batch agent testing | | Object | object | Query Salesforce SObjects | | DataModelObject | data_model_object | Query Data Cloud DMOs | | Evaluation | eval/* | Evaluate outputs (12 evaluation types) | | Reference | reference | Extract fields via JSON path | | Formula | formula | Computed values | | PromptTemplate | prompt_template | Execute prompt templates | | InvocableAction | invocable_action | Execute Flows/Apex | | Action | action | Standard platform actions | | Text | text | Static/editable text |

Model Shorthands

Use short names instead of full sfdc_ai__* identifiers:

| Shorthand | Model | |-----------|-------| | gpt-4-omni | GPT 4 Omni | | gpt-4-omni-mini | GPT 4 Omni Mini | | gpt-4.1 | GPT 4.1 | | gpt-4.1-mini | GPT 4.1 Mini | | gpt-5 | GPT 5 | | gpt-5-mini | GPT 5 Mini | | o3 | O3 | | o4-mini | O4 Mini | | claude-4.5-sonnet | Claude 4.5 Sonnet | | claude-4.5-haiku | Claude 4.5 Haiku | | claude-4-sonnet | Claude 4 Sonnet | | gemini-2.5-flash | Gemini 2.5 Flash | | gemini-2.5-flash-lite | Gemini 2.5 Flash Lite | | gemini-2.5-pro | Gemini 2.5 Pro | | nova-lite | Amazon Nova Lite | | nova-pro | Amazon Nova Pro |

Validation

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

Schema — required fields, valid types
Type-specific fields — each column type's required config
Reference integrity — all column name references resolve
Cycle detection — no circular dependencies (Kahn's algorithm)
Type compatibility — eval targets valid column types
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

Grid Connect MCP Server