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/

2. 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

3. 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:

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