Content
# Grid Connect MCP Server
MCP server for [Agentforce Grid](https://help.salesforce.com/s/articleView?id=sf.ai_workbench.htm) (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
1. **Login to your Salesforce org:**
```bash
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/
```
2. **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
```
3. **Install and build:**
```bash
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):**
```json
{
"mcpServers": {
"grid-connect": {
"command": "node",
"args": ["/path/to/agentforce-grid-mcp/dist/index.js"]
}
}
}
```
**With specific org:**
```json
{
"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:
```yaml
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
```bash
npm run build # Compile TypeScript
npm run dev # Watch mode
npm start # Run the server
```
