Salesforce MCP Library

Open-source bridge connecting AI agents to Salesforce via Model Context Protocol.

Two packages, zero external dependencies:

How it works

1. MCP Client (Claude, ChatGPT, any MCP host) sends JSON-RPC 2.0 messages over stdio
2. npm proxy authenticates via OAuth 2.0 (client credentials or per-user login), forwards requests over HTTPS, and handles token refresh automatically
3. Apex MCP Server dispatches requests to your registered tools, resources, and prompts — all running inside Salesforce with full platform security

Steps 1–2 apply when using the npm proxy. If your MCP host can reach the Apex endpoint directly over HTTPS with a valid Bearer token, only step 3 is required.

The Apex server is stateless — it rebuilds its handler chain on every request. No session cleanup, no state bugs, no cross-request data leakage.

When you need the proxy (and when you don't)

The Apex @RestResource endpoint is the MCP server — it implements JSON-RPC 2.0, capability negotiation, and all tool/resource/prompt dispatch. The TypeScript proxy is an authentication and transport bridge, not protocol logic. Most MCP clients support both stdio and HTTP, so the proxy's main value is not the transport — it is OAuth token lifecycle management: acquire a token, cache it, refresh it on expiry, and re-authenticate on 401. Configure once, run forever.

You need the proxy when your MCP host does not manage Salesforce OAuth tokens on its own. This covers most desktop clients (Claude Desktop, Cursor, VS Code extensions) and any integration without a built-in Salesforce credential store.

You can skip the proxy when the consumer already handles Salesforce OAuth — for example, a cloud platform with native Salesforce connectors, an automation service like n8n, or a custom agent orchestration layer that acquires tokens, fires an agent with MCP, routes the response back, and repeats. The Apex endpoint is stateless, so there is no session to maintain between calls.

If you remove the proxy, you are not removing complexity. You are taking ownership of it in another place — specifically, OAuth token acquisition, refresh logic, and session management move into your consumer.

For a deeper discussion of both paths and the direct-connection requirements, see docs/architecture.md.

Security — 4 layers, 3 of them automatic

Why External Client Apps

This library uses the OAuth 2.0 client_credentials flow and is runtime-agnostic about which Salesforce app container issued the credentials. The project documentation intentionally standardizes on External Client Apps (ECA) so setup guidance stays ahead of Salesforce's platform direction.

Quick start

1. Install the Apex framework

sf package install --package 04tdL000000So9xQAC --target-org YOUR_ORG --wait 10

2. Create your MCP endpoint (2 Apex classes)

Endpoint — a @RestResource that wires up your capabilities. In this unlocked package, the framework API stays public; the endpoint itself is global because Apex REST entry points require it:

@RestResource(urlMapping='/mcp/minimal')
global inherited sharing class MinimalMcpEndpoint {
    @HttpPost
    global static void handlePost() {
        McpServer server = new McpServer();
        server.registerTool(new MinimalTool());
        server.handleRequest(RestContext.request, RestContext.response);
    }
}

Tool — extend the package's public McpToolDefinition base class and implement inputSchema(), validate(), execute():

public inherited sharing class MinimalTool extends McpToolDefinition {
    public MinimalTool() {
        this.name = 'echo';
        this.description = 'Echoes the provided message back to the caller';
    }
    public override Map<String, Object> inputSchema() {
        return new Map<String, Object>{
            'type' => 'object',
            'properties' => new Map<String, Object>{
                'message' => new Map<String, Object>{
                    'type' => 'string',
                    'description' => 'The message to echo'
                }
            },
            'required' => new List<String>{ 'message' }
        };
    }
    public override void validate(Map<String, Object> arguments) {
        if (!arguments.containsKey('message')) {
            throw new McpInvalidParamsException('message is required');
        }
    }
    public override McpToolResult execute(Map<String, Object> arguments) {
        String msg = (String) arguments.get('message');
        McpToolResult result = new McpToolResult();
        result.content = new List<McpTextContent>{ new McpTextContent(msg) };
        return result;
    }
}

3. Configure an External Client App

Option A — Client Credentials (service account, no user interaction):
Create an External Client App with OAuth 2.0 Client Credentials flow. Note the client_id and client_secret.

Option B — Per-User Auth (individual identity, recommended):
Create an External Client App with Authorization Code + PKCE flow. Callback URL: http://localhost:13338/oauth/callback. Scopes: api, refresh_token. See Per-User Auth Setup Guide for detailed steps.

4. Connect an AI agent

Per-User Auth (individual identity — recommended for Claude Code):

# One-time login in your terminal:
npx salesforce-mcp-lib login \
  --instance-url https://your-org.my.salesforce.com \
  --client-id YOUR_CLIENT_ID

Then add to Claude Code via /mcp → Add Server, or edit ~/.claude.json:

{
  "mcpServers": {
    "salesforce": {
      "command": "npx",
      "args": [
        "-y", "salesforce-mcp-lib",
        "--instance-url", "https://your-org.my.salesforce.com",
        "--client-id", "YOUR_CLIENT_ID",
        "--endpoint", "/services/apexrest/mcp/minimal"
      ]
    }
  }
}

Client Credentials (service account — existing behavior):

{
  "mcpServers": {
    "salesforce": {
      "command": "npx",
      "args": [
        "-y", "salesforce-mcp-lib",
        "--instance-url", "https://your-org.my.salesforce.com",
        "--client-id", "YOUR_CLIENT_ID",
        "--client-secret", "YOUR_CLIENT_SECRET",
        "--endpoint", "/services/apexrest/mcp/minimal"
      ]
    }
  }
}

The auth mode is auto-detected: --client-secret present → client credentials, absent → per-user auth.

That's it. The agent can now discover and invoke your Salesforce tools.

inherited sharing and with sharing help enforce record-level access defaults, but they don't enforce CRUD/FLS by themselves. Use explicit security checks when your tool reads or writes protected fields or objects.

All three MCP capabilities

Register tools, resources, and prompts in a single endpoint:

@RestResource(urlMapping='/mcp/e2e')
global inherited sharing class E2eHttpEndpoint {
    @HttpPost
    global static void handlePost() {
        McpServer server = new McpServer();
        server.registerTool(new ExampleQueryTool());
        server.registerResource(new ExampleOrgResource());
        server.registerPrompt(new ExampleSummarizePrompt());
        server.handleRequest(RestContext.request, RestContext.response);
    }
}

See examples/ for complete working code.

CLI reference

MCP Server Mode

salesforce-mcp-lib [options]

* When --client-secret is provided → client credentials flow. When omitted → per-user auth (requires prior login).

Login Subcommand (per-user auth)

salesforce-mcp-lib login [options]

Tech stack

• Apex: Salesforce API 65.0 — 54 classes, zero external dependencies
• TypeScript: ES2022, Node.js >= 20 — 10 modules, zero npm production dependencies
• Protocol: MCP 2025-11-25, JSON-RPC 2.0 — all 11 MCP methods implemented
• Packaging: Salesforce 2GP unlocked package (no namespace)

Project structure

force-app/main/
  json-rpc/classes/    # JSON-RPC 2.0 core (14 classes)
  mcp/classes/         # MCP server framework (40 classes)
packages/salesforce-mcp-lib/
  src/                 # TypeScript stdio proxy (10 modules)
  tests/               # Unit tests
examples/
  minimal/             # Single-tool echo example
  e2e-http-endpoint/   # Tools + resources + prompts
scripts/               # Build, deploy, and release scripts

Contributing

Contributions are welcome. Validate Apex changes in a fresh scratch org before submitting:

./scripts/org-create.sh your-alias
./scripts/org-test.sh

org-create.sh provisions a new scratch org, sets it as default, and deploys force-app. org-test.sh then runs the Apex test suite in that org. Run the existing TypeScript test suite as well before submitting:

cd packages/salesforce-mcp-lib && npm test && npm run lint

License

MIT