@salesforce/sf-grid-mcp

Status: Beta — released in line with the Agentforce Grid GA. APIs may change as we iterate.

MCP server for Agentforce Grid (formerly AI Workbench). Exposes the Grid Connect API to LLM agents (Claude Code, Cursor, ChatGPT desktop, VS Code Copilot) via the Model Context Protocol. Distributed as a standalone npm package — invoked by your MCP client via npx. Authenticates against your existing sf CLI org auth — no tokens to manage.

Why this exists

Building Agentforce Grid workbooks by hand is iterative: create workbook, create worksheet, create columns one-by-one, wire up agent IDs, populate data. With this MCP, an LLM agent can drive that flow end-to-end via natural language — and the apply_grid tool collapses 10–15 sequential calls into a single declarative YAML spec.

Highlights

• 10 consolidated MCP tools — action-discriminated CRUD plus composite workflows
• apply_grid — create an entire grid from a single YAML spec
• discover — single tool for all 25+ metadata/data/agent discovery queries
• Typed mutations — edit_ai_prompt, change_model, add_evaluation, etc., as flat parameters instead of raw JSON
• 20 model shorthands — write claude-4.5-sonnet instead of sfdc_ai__DefaultClaude45Sonnet
• Hardened request logic — retry on network errors, 429 rate-limit respect, 5xx exponential backoff

Quick Start

1. Install the Salesforce CLI

brew install sf            # macOS
npm install -g @salesforce/cli   # any platform

2. Log into the org you want the MCP to use

sf org login web --alias my-org

Or use whichever org alias / username you've already set up.

3. Configure your MCP client

You don't install this package directly — your MCP client invokes it via npx -y and Node fetches it from the npm registry on first run.

Claude Code (.mcp.json in your project, or ~/.claude/mcp.json globally):

{
  "mcpServers": {
    "sf-grid": {
      "command": "npx",
      "args": ["-y", "@salesforce/sf-grid-mcp", "--orgs", "DEFAULT_TARGET_ORG"]
    }
  }
}

Cursor (mcp.json):

{
  "mcpServers": {
    "sf-grid": {
      "command": "npx",
      "args": ["-y", "@salesforce/sf-grid-mcp", "--orgs", "DEFAULT_TARGET_ORG"]
    }
  }
}

VS Code / GitHub Copilot (.vscode/mcp.json):

{
  "servers": {
    "sf-grid": {
      "command": "npx",
      "args": ["-y", "@salesforce/sf-grid-mcp", "--orgs", "DEFAULT_TARGET_ORG"]
    }
  }
}

CLI flags

| Flag | Description | |---|---| | --orgs | Required. Comma-separated list. Accepts DEFAULT_TARGET_ORG, ALLOW_ALL_ORGS, or specific org aliases / usernames (e.g. [email protected],my-alias). | | --instance-url | Override instance URL (advanced; usually inferred from sf CLI). | | --api-version | Salesforce API version (default: v66.0). | | --timeout-ms | HTTP request timeout in milliseconds (default: 60000). | | --debug | Enable debug logging on stderr. |

Choosing the right --orgs value

| Value | When to use | |---|---| | DEFAULT_TARGET_ORG | Recommended default. Uses whichever org sf config get target-org returns. | | my-alias | Pin the MCP to a specific org regardless of what your default-target-org is. | | ALLOW_ALL_ORGS | All authenticated orgs available; the LLM picks via tool calls. Use cautiously — agents can hit any org you've logged into. |

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, and a dryRun mode for validation without API calls.

Tool Categories

Typed Mutations

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

Standard operations for workbooks, worksheets, columns, cells, rows. Each is consolidated into a single MCP tool with an action parameter (e.g. workbook handles list, create, create_with_worksheet, get, get_worksheets, delete).

Discovery

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

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

Troubleshooting

Salesforce CLI (sf) is required but not found on PATH

The MCP server shells out to the sf CLI for every API call. Install it (brew install sf or npm install -g @salesforce/cli) and confirm sf --version works in the same shell your MCP client launches.

No org authenticated / No default org found

Run sf org login web --alias my-org, then either:

• Pass --orgs my-org to pin the MCP to that alias, or
• Run sf config set target-org=my-org and use --orgs DEFAULT_TARGET_ORG.

MCP client can't find sf-grid-mcp

Make sure your client config uses "command": "npx" and "args": ["-y", "@salesforce/sf-grid-mcp", ...] — the -y is required to auto-fetch the package on first run. If npx itself isn't on PATH, install Node 18+.

403 / INSUFFICIENT_ACCESS_OR_READONLY errors from the Grid API

The user behind your sf org login needs Agentforce Grid access in that org. Check with the org admin that the user's profile/permission set grants the relevant permissions on AIWorksheet* entities and the Grid Connect API.

Tool calls hang or time out

Bump --timeout-ms (default 60000). For long-running grid runs, prefer poll_worksheet_status rather than waiting on a single synchronous call.

Debug mode

Pass --debug to log every API call and response (status, duration) to stderr. Most MCP clients show server stderr in their logs panel.

Development

git clone https://github.com/salesforcecli/sf-grid-mcp.git
cd sf-grid-mcp
npm install
npm run build      # Compile TypeScript
npm run dev        # Watch mode (rebuild on save)
npm test           # Unit tests (offline)
npm run evals      # Integration tests against an authenticated org (see evals/README.md)

To test a local build against an MCP client, point the client at the absolute path of dist/index.js instead of npx -y @salesforce/sf-grid-mcp:

{
  "mcpServers": {
    "sf-grid-local": {
      "command": "node",
      "args": ["/path/to/sf-grid-mcp/dist/index.js", "--orgs", "DEFAULT_TARGET_ORG"]
    }
  }
}

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               # workbook (list, create, create_with_worksheet, get, get_worksheets, delete)
    worksheet.ts              # worksheet (create, get, get_data, update, delete, add_rows, etc.)
    column.ts                 # column (CRUD + typed mutations like edit_ai_prompt, change_model)
    column-mutation.ts        # column_mutation (typed shorthands)
    cell.ts                   # cell (update, paste, trigger_execution, validate_formula, generate_ia_input)
    discover.ts               # discover (25 metadata/data/agent discovery actions)
    workflows.ts              # setup_agent_test, poll_worksheet_status, get_worksheet_summary
    apply-grid.ts             # apply_grid (YAML DSL → entire grid in one call)
    urls.ts                   # 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
    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

License

Apache-2.0 — see LICENSE.txt.

Contributing

See CONTRIBUTING.md.

Changelog

See CHANGELOG.md for release history.