Salesforce MCP Library

https://github.com/damecek/salesforce-mcp-lib
Admin
Salesforce MCP Library is a local stdio bridge for Salesforce MCP endpoints using OAuth client...
Tokens:72,034
Snippets:566
Trust Score:7.5
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Bash: Login and Start MCP Server for Carvago Org

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/003-per-user-auth/quickstart.md

Commands to log in and start the MCP server for manual testing against the Carvago org. The login command opens a browser for OAuth, and the server start command uses the same credentials. Tokens are stored in ~/.salesforce-mcp-lib/tokens/.

```bash
# Step 1: Login
npx salesforce-mcp-lib login \
  --instance-url https://carvago.my.salesforce.com \
  --client-id 3MVG9fTLmJ60pJ5LtEXrrYU_yvTMZwYXbrMNq0Nj0Dsk2snkXq4LZYtyJx7ACykA_qWQhBMIdudcm.h7xCuOs

# Step 2: Start MCP server (for manual testing)
npx salesforce-mcp-lib \
  --instance-url https://carvago.my.salesforce.com \
  --client-id 3MVG9fTLmJ60pJ5LtEXrrYU_yvTMZwYXbrMNq0Nj0Dsk2snkXq4LZYtyJx7ACykA_qWQhBMIdudcm.h7xCuOs \
  --sf-endpoint /services/apexrest/mcp/records
```

--------------------------------

### Subscriber Implementation Example: SummarizeOpportunityPrompt

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/001-apex-mcp-server/contracts/apex-public-api.md

Concrete example of a subscriber that extends McpPromptDefinition. Sets the prompt name, description, and argument definitions in the constructor, and overrides the get method to query an Opportunity and build a prompt message. Returns a McpPromptResult with a single user message containing the prompt text.

```apex
public class SummarizeOpportunityPrompt extends McpPromptDefinition {

    public SummarizeOpportunityPrompt() {
        this.name = 'summarize_opportunity';
        this.description = 'Generate a summary prompt for a Salesforce Opportunity';
        this.arguments = new List<McpPromptArgumentDefinition>{
            new McpPromptArgumentDefinition('opportunityId', 'Salesforce Opportunity ID', true)
        };
    }

    public override McpPromptResult get(Map<String, String> arguments) {
        String oppId = arguments.get('opportunityId');
        Opportunity opp = [
            SELECT Name, Amount, StageName, CloseDate, Account.Name
            FROM Opportunity
            WHERE Id = :oppId
            LIMIT 1
        ];

        String promptText = 'Summarize this Salesforce Opportunity:\n\n'
            + 'Name: ' + opp.Name + '\n'
            + 'Account: ' + opp.Account.Name + '\n'
            + 'Amount: $' + opp.Amount + '\n'
            + 'Stage: ' + opp.StageName + '\n'
            + 'Close Date: ' + String.valueOf(opp.CloseDate);

        McpPromptResult result = new McpPromptResult();
        result.messages = new List<McpPromptMessage>{
            new McpPromptMessage('user', new McpTextContent(promptText))
        };
        return result;
    }
}
```

--------------------------------

### Install and verify SalesforceMcpLib package

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/001-apex-mcp-server/quickstart.md

Install the 2GP unlocked package into your org and verify the installation. The first command installs SalesforceMcpLib@1.1.0-1 with a 10-minute wait; the second lists installed packages to confirm SalesforceMcpLib appears.

```bash
sf package install \
  --package SalesforceMcpLib@1.1.0-1 \
  --target-org my-org \
  --wait 10
```

```bash
sf package installed list --target-org my-org
```

--------------------------------

### Start MCP Inspector with salesforce-mcp-lib

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/001-apex-mcp-server/quickstart.md

Starts the MCP Inspector with the salesforce-mcp-lib proxy to test the MCP server. Replace the placeholder values with your actual instance URL, consumer key, and consumer secret.

```bash
npx @modelcontextprotocol/inspector \
  npx salesforce-mcp-lib \
    --instance-url https://your-org.my.salesforce.com \
    --client-id YOUR_CONSUMER_KEY \
    --client-secret YOUR_CONSUMER_SECRET \
    --endpoint /services/apexrest/mcp/v1
```

--------------------------------

### Per-User Auth First-Time Login (Interactive)

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/003-per-user-auth/contracts/cli-contract.md

Two-step process: first run the login subcommand to authenticate interactively, then start the MCP server using the stored tokens.

```bash
# Step 1: Login (one-time, interactive)
salesforce-mcp-lib login \
  --instance-url https://myorg.my.salesforce.com \
  --client-id 3MVG9...

# Browser opens → user logs in → tokens stored locally
```

```bash
# Step 2: Start MCP server (uses stored tokens)
salesforce-mcp-lib \
  --instance-url https://myorg.my.salesforce.com \
  --client-id 3MVG9... \
  --endpoint /services/apexrest/mcp
```

--------------------------------

### QueryAccountsTool subscriber implementation example

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/001-apex-mcp-server/contracts/apex-public-api.md

Concrete example of a subscriber extending McpToolDefinition. Implements inputSchema, validate, and execute methods. The validate method throws McpInvalidParamsException for missing or too-short searchTerm. The execute method queries Account records and returns them as McpTextContent.

```apex
public with sharing class QueryAccountsTool extends McpToolDefinition {

    public QueryAccountsTool() {
        this.name = 'query_accounts';
        this.description = 'Search for Salesforce Account records by name';
    }

    public override Map<String, Object> inputSchema() {
        return new Map<String, Object>{
            'type' => 'object',
            'properties' => new Map<String, Object>{
                'searchTerm' => new Map<String, Object>{
                    'type' => 'string',
                    'description' => 'Account name search term'
                },
                'maxResults' => new Map<String, Object>{
                    'type' => 'integer',
                    'description' => 'Maximum number of results (default 10)'
                }
            },
            'required' => new List<String>{ 'searchTerm' }
        };
    }

    public override void validate(Map<String, Object> arguments) {
        if (!arguments.containsKey('searchTerm')) {
            throw new McpInvalidParamsException('searchTerm is required');
        }
        String term = (String) arguments.get('searchTerm');
        if (String.isBlank(term) || term.length() < 2) {
            throw new McpInvalidParamsException(
                'searchTerm must be at least 2 characters'
            );
        }
    }

    public override McpToolResult execute(Map<String, Object> arguments) {
        String term = (String) arguments.get('searchTerm');
        Integer maxResults = arguments.containsKey('maxResults')
            ? (Integer) arguments.get('maxResults')
            : 10;

        List<Account> accounts = [
            SELECT Id, Name, Industry
            FROM Account
            WHERE Name LIKE :('%' + term + '%')
            LIMIT :maxResults
        ];

        McpToolResult result = new McpToolResult();
        result.content = new List<McpTextContent>{
            new McpTextContent(JSON.serialize(accounts))
        };
        return result;
    }
}
```

--------------------------------

### salesforce-mcp-lib [options]

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/README.md

CLI command to start the MCP server. It requires Salesforce org URL, client ID, and endpoint path, with optional client secret, callback port, and log level.

```APIDOC
## [CLI] salesforce-mcp-lib [options]

### Description
Starts the MCP server with the given options.

### Method
CLI

### Endpoint
salesforce-mcp-lib [options]

### Parameters
#### Options
- **--instance-url** (string) - Required - Salesforce org URL (env: SF_INSTANCE_URL)
- **--client-id** (string) - Required - External Client App consumer key (env: SF_CLIENT_ID)
- **--client-secret** (string) - Optional - External Client App consumer secret (env: SF_CLIENT_SECRET)
- **--endpoint** (string) - Required - Apex REST endpoint path (env: SF_ENDPOINT)
- **--callback-port** (number) - Optional - Local OAuth callback port (default: 13338) (env: SF_CALLBACK_PORT)
- **--log-level** (string) - Optional - debug/info/warn/error (default: info) (env: SF_LOG_LEVEL)

### Response
(No response documented)
```

--------------------------------

### Run MCP server with CLI options

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/README.md

Starts the MCP server. Requires --instance-url, --client-id, and --endpoint. Use --client-secret for client credentials flow; omit for per-user auth.

```text
salesforce-mcp-lib [options]
```

--------------------------------

### Install Apex framework package

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/README.md

Installs the unlocked Apex framework package into your Salesforce org. Replace YOUR_ORG with your target org alias or username.

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

--------------------------------

### Configure Claude Desktop MCP server for salesforce-mcp-lib

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/003-per-user-auth/quickstart.md

Configuration for Claude Desktop. Add this to claude_desktop_config.json. Run npx salesforce-mcp-lib login first before starting Claude Desktop.

```json
{
  "mcpServers": {
    "salesforce": {
      "command": "npx",
      "args": [
        "-y", "salesforce-mcp-lib",
        "--instance-url", "https://myorg.my.salesforce.com",
        "--client-id", "3MVG9...your_consumer_key",
        "--sf-endpoint", "/services/apexrest/mcp/records"
      ]
    }
  }
}
```

--------------------------------

### Documentation file structure

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/003-per-user-auth/plan.md

Shows the documentation file structure for this feature, including the plan, research, data-model, quickstart, contracts, and tasks files.

```text
specs/003-per-user-auth/
├── plan.md              # This file (/speckit.plan command output)
├── research.md          # Phase 0 output
├── data-model.md        # Phase 1 output
├── quickstart.md        # Phase 1 output
├── contracts/
│   ├── cli-contract.md  # Phase 1 output — CLI interface changes
│   └── api-contract.md  # Phase 1 output — TypeScript API changes
└── tasks.md             # Phase 2 output (/speckit.tasks command)
```

--------------------------------

### salesforce-mcp-lib [options]

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/packages/salesforce-mcp-lib/README.md

Starts the MCP server proxy that connects to a Salesforce Apex REST endpoint. Requires instance URL, client ID, and endpoint; optionally supports client secret for client credentials flow.

```APIDOC
## CLI: salesforce-mcp-lib [options]

### Description
Starts the MCP server proxy that connects to a Salesforce Apex REST endpoint. Requires instance URL, client ID, and endpoint; optionally supports client secret for client credentials flow.

### Usage
```
salesforce-mcp-lib [options]
```

### Parameters
#### CLI Flags / Environment Variables
- `--instance-url` / `SF_INSTANCE_URL` (string) - Required - Salesforce org URL
- `--client-id` / `SF_CLIENT_ID` (string) - Required - External Client App consumer key
- `--client-secret` / `SF_CLIENT_SECRET` (string) - Optional - External Client App consumer secret. When provided, uses client credentials flow; when omitted, uses per-user auth (requires prior `login`).
- `--endpoint` / `SF_ENDPOINT` (string) - Required - Apex REST endpoint path
- `--callback-port` / `SF_CALLBACK_PORT` (number) - Optional - OAuth callback port (default: `13338`)
- `--log-level` / `SF_LOG_LEVEL` (string) - Optional - Log level: `debug`, `info`, `warn`, `error` (default: `info`)

### Notes
- When `--client-secret` is provided, the client credentials flow is used. When omitted, per-user auth is used (requires prior `login`).
```

--------------------------------

### Run MCP Server Directly with npx

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/packages/salesforce-mcp-lib/README.md

Run the MCP server directly without installation. Includes both client credentials and endpoint configuration.

```bash
npx 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
```

--------------------------------

### prompts/get Request

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/001-apex-mcp-server/contracts/mcp-json-rpc.md

Request to get a specific prompt by name and provide arguments. The name must match a registered prompt.

```json
{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "prompts/get",
  "params": {
    "name": "summarize_opportunity",
    "arguments": {
      "opportunityId": "006xx000001Sv6yAAC"
    }
  }
}
```

--------------------------------

### Bash: Client Credentials Auth Mode

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/003-per-user-auth/quickstart.md

Command to start the MCP server using client credentials flow. This is the existing behavior when --client-secret is provided. The server uses the specified instance URL, client ID, and secret.

```bash
npx salesforce-mcp-lib \
  --instance-url https://myorg.my.salesforce.com \
  --client-id 3MVG9... \
  --client-secret YOUR_SECRET \
  --sf-endpoint /services/apexrest/mcp/records
```

--------------------------------

### Bash: Per-User Auth Mode

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/003-per-user-auth/quickstart.md

Command to start the MCP server using per-user auth. This is the new behavior when --client-secret is omitted. The mode is auto-detected, no explicit flag needed.

```bash
npx salesforce-mcp-lib \
  --instance-url https://myorg.my.salesforce.com \
  --client-id 3MVG9... \
  --sf-endpoint /services/apexrest/mcp/records
```

--------------------------------

### Callback Server Interfaces and startCallbackServer

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/003-per-user-auth/contracts/api-contract.md

Callback server interfaces and start function. Default port is 13338, default timeout is 120000 ms. The server attempts the configured port and increments up to 5 times if occupied. waitForCode resolves with code and state.

```typescript
export interface CallbackServerOptions {
  /** Port to listen on. Defaults to 13338. */
  port?: number;
  /** Timeout in milliseconds. Defaults to 120000 (2 minutes). */
  timeout?: number;
}

export interface CallbackServer {
  /** The port the server is actually listening on. */
  readonly port: number;
  /** The full callback URL (http://localhost:{port}/oauth/callback). */
  readonly callbackUrl: string;
  /** Wait for the authorization code. Resolves with code + state. */
  waitForCode(): Promise<CallbackResult>;
  /** Shut down the server. */
  close(): void;
}

export interface CallbackResult {
  code: string;
  state: string;
}

/**
 * Start a local HTTP server that waits for the OAuth callback.
 * Attempts the configured port first, then increments up to 5 times if occupied.
 */
export function startCallbackServer(options?: CallbackServerOptions): Promise<CallbackServer>;
```

--------------------------------

### initialize response (success)

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/001-apex-mcp-server/contracts/mcp-json-rpc.md

Returned by the server on successful initialization. Contains protocolVersion, capabilities (tools, resources, prompts), and serverInfo (name required, version optional).

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-11-25",
    "capabilities": {
      "tools": {},
      "resources": {},
      "prompts": {}
    },
    "serverInfo": {
      "name": "SalesforceMcpServer",
      "version": "1.1.0"
    }
  }
}
```

--------------------------------

### Deploy source to org

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/001-apex-mcp-server/quickstart.md

Deploy the source directory to your org using Salesforce CLI.

```bash
sf project deploy start \
  --source-dir force-app \
  --target-org my-org
```

--------------------------------

### salesforce-mcp-lib login [options]

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/README.md

CLI subcommand for per-user authentication. It requires Salesforce org URL and client ID, with optional headless mode and callback port.

```APIDOC
## [CLI] salesforce-mcp-lib login [options]

### Description
Performs per-user authentication for the MCP server.

### Method
CLI

### Endpoint
salesforce-mcp-lib login [options]

### Parameters
#### Options
- **--instance-url** (string) - Required - Salesforce org URL (env: SF_INSTANCE_URL)
- **--client-id** (string) - Required - External Client App consumer key (env: SF_CLIENT_ID)
- **--headless** (boolean) - Optional - Print auth URL instead of opening browser (env: SF_HEADLESS)
- **--callback-port** (number) - Optional - Local OAuth callback port (default: 13338) (env: SF_CALLBACK_PORT)

### Response
(No response documented)
```

--------------------------------

### Parallel and sequential tasks for User Story 2

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/003-per-user-auth/tasks.md

Task breakdown for User Story 2. T013 and T014 are independent and can start immediately in Phase 4; T015 and T016 depend on them.

```bash
# Token store is independent of refresh implementation:
Task T013: "Create tokenStore.ts" (can start immediately in Phase 4)
Task T014: "refreshAccessToken in perUserAuth.ts" (can start immediately in Phase 4)

# Then integration (depends on T013, T014):
Task T015: "Integrate persistence into PerUserAuthStrategy"
Task T016: "Update index.ts startup with token loading"
```

--------------------------------

### Implement DescribeObjectPrompt class

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/001-apex-mcp-server/quickstart.md

Defines a prompt that accepts an objectName argument to describe a specific Salesforce object.

```apex
public inherited sharing class DescribeObjectPrompt extends McpPromptDefinition {

    public DescribeObjectPrompt() {
        this.name = 'describe_object';
        this.description = 'Generate a prompt to describe a Salesforce object';
        this.arguments = new List<McpPromptArgumentDefinition>{
            new McpPromptArgumentDefinition('objectName', 'API name of the Salesforce object', true)
        };
    }

    public override McpPromptResult get(Map<String, String> arguments) {
        String objName = arguments.get('objectName');
        Schema.DescribeSObjectResult describe = Schema.getGlobalDescribe().get(objName).getDescribe();

        String text = 'Describe the Salesforce object: ' + describe.getLabel()
            + ' (API name: ' + describe.getName() + ')\n'
            + 'Fields: ' + describe.fields.getMap().size() + '\n'
            + 'Custom: ' + describe.isCustom();

        McpPromptResult result = new McpPromptResult();
        result.messages = new List<McpPromptMessage>{
            new McpPromptMessage('user', new McpTextContent(text))
        };
        return result;
    }
}
```

--------------------------------

### JSON: Claude Code MCP Server Configuration

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/003-per-user-auth/quickstart.md

Configuration for Claude Code to connect to the MCP server. The server is started via npx with the specified arguments. This configuration is used for testing with Claude Code.

```json
{
  "mcpServers": {
    "salesforce": {
      "command": "npx",
      "args": [
        "-y", "salesforce-mcp-lib",
        "--instance-url", "https://carvago.my.salesforce.com",
        "--client-id", "3MVG9fTLmJ60pJ5LtEXrrYU_yvTMZwYXbrMNq0Nj0Dsk2snkXq4LZYtyJx7ACykA_qWQhBMIdudcm.h7xCuOs",
        "--sf-endpoint", "/services/apexrest/mcp/records"
      ]
    }
  }
}
```

--------------------------------

### Login subcommand for per-user auth

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/README.md

Performs per-user authentication. Requires --instance-url and --client-id. Use --headless to print the auth URL instead of opening a browser.

```text
salesforce-mcp-lib login [options]
```

--------------------------------

### Implement QueryAccountsTool and MyMcpEndpoint

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/001-apex-mcp-server/quickstart.md

Create a tool class extending McpToolDefinition and a REST endpoint that registers it. The tool defines input schema, validation, and execution; the endpoint uses @RestResource and delegates to McpServer. Note that 'inherited sharing' and 'with sharing' do not enforce CRUD/FLS by themselves.

```apex
public with sharing class QueryAccountsTool extends McpToolDefinition {

    public QueryAccountsTool() {
        this.name = 'query_accounts';
        this.description = 'Search for Salesforce Account records by name';
    }

    public override Map<String, Object> inputSchema() {
        return new Map<String, Object>{
            'type' => 'object',
            'properties' => new Map<String, Object>{
                'searchTerm' => new Map<String, Object>{
                    'type' => 'string',
                    'description' => 'Account name to search for'
                }
            },
            'required' => new List<String>{ 'searchTerm' }
        };
    }

    public override void validate(Map<String, Object> arguments) {
        if (!arguments.containsKey('searchTerm')) {
            throw new McpInvalidParamsException('searchTerm is required');
        }
    }

    public override McpToolResult execute(Map<String, Object> arguments) {
        String term = (String) arguments.get('searchTerm');
        List<Account> accounts = [
            SELECT Id, Name, Industry
            FROM Account
            WHERE Name LIKE :('%' + term + '%')
            LIMIT 10
        ];

        McpToolResult result = new McpToolResult();
        result.content = new List<McpTextContent>{
            new McpTextContent(JSON.serialize(accounts))
        };
        return result;
    }
}
```

```apex
@RestResource(urlMapping='/mcp/v1')
global inherited sharing class MyMcpEndpoint {

    @HttpPost
    global static void handlePost() {
        McpServer server = new McpServer();

        // Register your tools
        server.registerTool(new QueryAccountsTool());

        // Delegate to the MCP framework
        server.handleRequest(RestContext.request, RestContext.response);
    }
}
```

--------------------------------

### Existing Client Credentials Usage (CLI flags and Environment Variables)

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/003-per-user-auth/contracts/cli-contract.md

Two ways to run the MCP server with client credentials: via CLI flags or environment variables. Both are unchanged from v1.0.x.

```bash
# Via CLI flags
salesforce-mcp-lib \
  --instance-url https://myorg.my.salesforce.com \
  --client-id 3MVG9... \
  --client-secret ABCDEF... \
  --endpoint /services/apexrest/mcp
```

```bash
# Via environment variables
SF_INSTANCE_URL=https://myorg.my.salesforce.com \
SF_CLIENT_ID=3MVG9... \
SF_CLIENT_SECRET=ABCDEF... \
SF_ENDPOINT=/services/apexrest/mcp \
salesforce-mcp-lib
```

--------------------------------

### McpPromptDefinition abstract class definition

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/001-apex-mcp-server/contracts/apex-public-api.md

Defines the abstract base class for MCP prompts. Includes public fields for name, description, and arguments, and an abstract get method that returns McpPromptResult. Use as a base for custom prompt implementations.

```apex
public abstract class McpPromptDefinition {

    /** Unique prompt name. */
    public String name;

    /** Description. */
    public String description;

    /** Argument definitions. */
    public List<McpPromptArgumentDefinition> arguments;

    /**
     * Generate prompt messages for the given arguments.
     * @param arguments Key-value map of prompt arguments
     * @return McpPromptResult containing messages
     */
    public abstract McpPromptResult get(Map<String, String> arguments);
}
```

--------------------------------

### Source code directory structure

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/001-apex-mcp-server/plan.md

Shows the repository root layout, including force-app/, packages/salesforce-mcp-lib/, scripts/, examples/, dev/mcp-harness/, config/, and docs/.

```text
force-app/                              # Salesforce 2GP package source
├── main/
│   ├── json-rpc/                      # JSON-RPC 2.0 core (in-repo)
│   │   └── classes/                   # ~19 classes: runtime, handlers, params, errors
│   └── mcp/                           # MCP 2025-11-25 layer
│       └── classes/                   # ~58 classes: server, tools, resources, prompts, transport

packages/salesforce-mcp-lib/            # TypeScript stdio proxy (npm package)
├── src/                               # 6 modules: index, types, config, oauth, mcpBridge, stdio, errors
├── tests/                             # Unit + E2E tests
├── dist/                              # Compiled JS output
├── package.json                       # npm metadata (salesforce-mcp-lib@1.0.2)
└── tsconfig.json                      # ES2022, NodeNext, strict

scripts/                                # 19 bash automation scripts
├── org-*.sh                           # Scratch org lifecycle
├── harness-*.sh                       # Development harness operations
├── release-*.sh                       # 2GP package release pipeline
├── validate.sh                        # Full validation suite
└── task-prepare*.sh                   # Feature work preparation

examples/                               # Reference implementations
├── minimal/                           # Bare-minimum tool example
└── e2e-http-endpoint/                 # Full endpoint pattern

dev/mcp-harness/                        # Development testing harness
├── force-app/                         # Test Apex classes (DevMcpHarness*)
└── inspector/                         # MCP Inspector configuration

config/                                 # Package configuration
├── package-version-def.json           # 2GP version definition
└── project-scratch-def.json           # Scratch org shape

docs/                                   # Design and audit documentation
├── mcp-wire-contract-audit-2025-11-25.md
└── mcp-authorization-feasibility-report-2026-03-22.md
```

--------------------------------

### initialize

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/001-apex-mcp-server/contracts/mcp-json-rpc.md

Initializes the MCP session between the client and server. The client sends its protocol version, capabilities, and client information; the server responds with its supported protocol version, capabilities, and server information.

```APIDOC
## initialize

### Description
Initializes the MCP session between the client and server. The client sends its protocol version, capabilities, and client information; the server responds with its supported protocol version, capabilities, and server information.

### Method
JSON-RPC

### Endpoint
N/A (JSON-RPC method)

### Parameters
#### Request Body
- **protocolVersion** (string) - Required - MCP protocol version
- **capabilities** (object) - Required - Client capabilities (may be empty)
- **clientInfo** (object) - Required - Client name (required) and version (optional)

### Request Example
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {
      "name": "ExampleClient",
      "version": "1.0.0"
    }
  }
}

### Response
#### Success Response (200)
- **protocolVersion** (string) - Server's supported protocol version
- **capabilities** (object) - Server capabilities (tools, resources, prompts as registered)
- **serverInfo** (object) - Server name (required) and version (optional)
- **instructions** (string) - LLM guidance hints (optional)

#### Response Example
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-11-25",
    "capabilities": {
      "tools": {},
      "resources": {},
      "prompts": {}
    },
    "serverInfo": {
      "name": "SalesforceMcpServer",
      "version": "1.1.0"
    }
  }
}
```

--------------------------------

### JSON-RPC Protocol Error Response

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/001-apex-mcp-server/contracts/mcp-json-rpc.md

Standard JSON-RPC error response format for protocol-level errors such as parse errors, invalid requests, method not found, invalid params, and internal errors. The example shows a 'Method not found' error with code -32601.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Method not found: unknown/method"
  }
}
```

--------------------------------

### MCP server mode stderr messages (per-user auth)

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/003-per-user-auth/contracts/cli-contract.md

Expected stderr output when starting the MCP server in per-user authentication mode. Shows the configuration details (instance URL, client ID, auth mode, endpoint) and the sequence of token loading, refreshing, and readiness for JSON-RPC messages.

```text
[INFO] salesforce-mcp-lib starting
[INFO]   instance-url : https://myorg.my.salesforce.com
[INFO]   client-id    : 3MVG9...(redacted)
[INFO]   auth-mode    : per-user (authorization code)
[INFO]   endpoint     : /services/apexrest/mcp
[INFO] Loaded stored tokens for myorg.my.salesforce.com
[INFO] Refreshing access token...
[INFO] Token refreshed successfully (user: user@example.com)
[INFO] Listening on stdin for JSON-RPC messages
```

--------------------------------

### Project structure tree

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/CLAUDE.md

Shows the source and test directory layout for the salesforce-mcp-lib package. Use it to understand where each module (CLI entry, config, OAuth, token store, MCP bridge, etc.) lives.

```text
packages/salesforce-mcp-lib/src/
  index.ts             # CLI entry point (login subcommand + MCP server)
  config.ts            # CLI argument / env-var parser
  types.ts             # Shared type definitions (AuthConfig, AuthMode, etc.)
  errors.ts            # Error class hierarchy (SalesforceAuthError + subclasses)
  oauth.ts             # Client credentials OAuth flow + ClientCredentialsStrategy
  authStrategy.ts      # AuthStrategy interface + PerUserAuthStrategy + factory
  perUserAuth.ts       # Authorization Code flow (PKCE, token exchange, browser)
  callbackServer.ts    # Local HTTP server for OAuth redirect callback
  tokenStore.ts        # File-based token persistence (~/.salesforce-mcp-lib/tokens/)
  mcpBridge.ts         # JSON-RPC forwarding to Salesforce Apex endpoint
  stdio.ts             # Stdio transport + levelled logger

packages/salesforce-mcp-lib/tests/
  *.test.ts            # Unit tests (node:test runner)
```

--------------------------------

### Implement OrgInfoResource class

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/001-apex-mcp-server/quickstart.md

Defines a resource that returns basic Salesforce organization information in JSON format.

```apex
public with sharing class OrgInfoResource extends McpResourceDefinition {

    public OrgInfoResource() {
        this.uri = 'salesforce://org/info';
        this.name = 'Org Info';
        this.description = 'Basic information about the Salesforce org';
        this.mimeType = 'application/json';
    }

    public override McpResourceResult read() {
        Organization org = [SELECT Name, OrganizationType, IsSandbox FROM Organization LIMIT 1];
        McpResourceResult result = new McpResourceResult();
        McpResourceContentItem item = new McpResourceContentItem();
        item.uri = this.uri;
        item.mimeType = this.mimeType;
        item.text = JSON.serialize(org);
        result.contents = new List<McpResourceContentItem>{ item };
        return result;
    }
}
```

--------------------------------

### Run tests and lint

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/CLAUDE.md

Runs the unit test suite and linter for the salesforce-mcp-lib package. Execute from the package directory.

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

--------------------------------

### Configure Proxy Instances for Multiple Endpoints

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/001-apex-mcp-server/quickstart.md

Use the CLI to point the proxy to specific Apex REST endpoints by providing the corresponding path in the --endpoint flag.

```bash
# Sales agent
npx salesforce-mcp-lib --endpoint /services/apexrest/mcp/sales ...

# Support agent
npx salesforce-mcp-lib --endpoint /services/apexrest/mcp/support ...
```

--------------------------------

### Documentation directory structure

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/001-apex-mcp-server/plan.md

Shows the layout of the specs/001-apex-mcp-server/ directory, including plan.md, research.md, data-model.md, quickstart.md, contracts/, and tasks.md.

```text
specs/001-apex-mcp-server/
├── plan.md              # This file (/speckit.plan command output)
├── research.md          # Phase 0 output (/speckit.plan command)
├── data-model.md        # Phase 1 output (/speckit.plan command)
├── quickstart.md        # Phase 1 output (/speckit.plan command)
├── contracts/           # Phase 1 output (/speckit.plan command)
└── tasks.md             # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
```

--------------------------------

### tools/list Request

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/001-apex-mcp-server/contracts/mcp-json-rpc.md

Request to list available tools. The optional cursor parameter is not implemented in v1.

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/list",
  "params": {}
}
```

--------------------------------

### initialize request

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/001-apex-mcp-server/contracts/mcp-json-rpc.md

Sent by the client to the server to initialize the MCP session. Requires protocolVersion, capabilities, and clientInfo (name required, version optional).

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {
      "name": "ExampleClient",
      "version": "1.0.0"
    }
  }
}
```

--------------------------------

### Per-User Auth Headless Login

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/003-per-user-auth/contracts/cli-contract.md

Login command with --headless flag prints a URL to stderr for manual authorization, then expects the user to paste the callback URL.

```bash
salesforce-mcp-lib login \
  --instance-url https://myorg.my.salesforce.com \
  --client-id 3MVG9... \
  --headless

# Output to stderr:
#   Please open this URL in a browser to authorize:
#   https://myorg.my.salesforce.com/services/oauth2/authorize?response_type=code&client_id=3MVG9...
#
#   After authorizing, paste the full callback URL:
# User pastes → tokens stored
```

--------------------------------

### resources/list Request

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/001-apex-mcp-server/contracts/mcp-json-rpc.md

Request to list all available resources. The method is 'resources/list' with an empty params object.

```json
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "resources/list",
  "params": {}
}
```

--------------------------------

### Login to Salesforce with salesforce-mcp-lib

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/003-per-user-auth/quickstart.md

One-time authentication for per-user mode. Opens a browser for Salesforce login, stores tokens in ~/.salesforce-mcp-lib/tokens/, and enables automatic token refresh.

```bash
npx salesforce-mcp-lib login \
  --instance-url https://myorg.my.salesforce.com \
  --client-id 3MVG9...your_consumer_key
```

--------------------------------

### Validate Apex changes with org-create.sh and org-test.sh

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/README.md

Validates Apex changes in a fresh scratch org before submitting. 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.

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

--------------------------------

### prompts/get

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/001-apex-mcp-server/contracts/mcp-json-rpc.md

Retrieves a specific prompt by name, optionally providing arguments. The prompt must be registered with the server.

```APIDOC
## prompts/get

### Description
Retrieves a specific prompt by name, optionally providing arguments.

### Method
JSON-RPC

### Endpoint
prompts/get

### Parameters
#### Request Body
- **name** (string) - Required - Prompt name (must match a registered prompt)
- **arguments** (object) - Optional - Prompt arguments (key-value strings)

### Request Example
{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "prompts/get",
  "params": {
    "name": "summarize_opportunity",
    "arguments": {
      "opportunityId": "006xx000001Sv6yAAC"
    }
  }
}

### Response
#### Success Response
- **description** (string) - Prompt description
- **messages** (array) - List of message objects
  - **role** (string) - Message role (e.g., "user")
  - **content** (object) - Message content
    - **type** (string) - Content type (e.g., "text")
    - **text** (string) - Text content

#### Response Example
{
  "jsonrpc": "2.0",
  "id": 8,
  "result": {
    "description": "Opportunity summary prompt",
    "messages": [
      {
        "role": "user",
        "content": {
          "type": "text",
          "text": "Summarize this Salesforce Opportunity:\n\nName: Big Deal\nAmount: $500,000\nStage: Negotiation\nClose Date: 2026-06-30"
        }
      }
    ]
  }
}
```

--------------------------------

### Source and test file structure

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/003-per-user-auth/plan.md

Shows the source and test file structure for the per-user auth feature, indicating which files are modified, new, or unchanged.

```text
packages/salesforce-mcp-lib/src/
├── types.ts             # MODIFY: Add AuthConfig, PerUserTokenData, AuthMode
├── config.ts            # MODIFY: clientSecret optional, add --headless, login subcommand
├── errors.ts            # MODIFY: Add auth-specific error subclasses
├── oauth.ts             # MODIFY: Refactor to implement AuthStrategy interface
├── authStrategy.ts      # NEW: AuthStrategy interface + factory
├── perUserAuth.ts       # NEW: Authorization Code flow implementation
├── tokenStore.ts        # NEW: File-based encrypted token persistence
├── callbackServer.ts    # NEW: Local HTTP server for OAuth redirect
├── index.ts             # MODIFY: Auth mode detection, login subcommand routing
├── mcpBridge.ts         # MODIFY: Use AuthStrategy for re-auth + token refresh
└── stdio.ts             # UNCHANGED

packages/salesforce-mcp-lib/tests/
├── perUserAuth.test.ts  # NEW: Per-user OAuth flow tests
├── tokenStore.test.ts   # NEW: Token persistence tests
├── callbackServer.test.ts # NEW: Callback server tests
├── authStrategy.test.ts # NEW: Strategy selection/factory tests
├── config.test.ts       # MODIFY: Test optional clientSecret, headless flag
└── oauth.test.ts        # MODIFY: Ensure existing client credentials tests pass
```

--------------------------------

### Headless login command

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/003-per-user-auth/quickstart.md

Use this command in SSH, Docker, or CI environments to initiate a headless login. It prints an authorization URL to open in any browser; after authorizing, paste the callback URL back into the terminal.

```bash
npx salesforce-mcp-lib login \
  --instance-url https://myorg.my.salesforce.com \
  --client-id 3MVG9... \
  --headless
```

--------------------------------

### prompts/list Request

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/001-apex-mcp-server/contracts/mcp-json-rpc.md

Request to list all available prompts. The method is 'prompts/list' with an empty params object.

```json
{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "prompts/list",
  "params": {}
}
```

--------------------------------

### Auth Mode Detection Flow (ASCII Diagram)

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/003-per-user-auth/contracts/cli-contract.md

Flowchart showing how the CLI decides between Client Credentials and Per-User Auth based on whether a client secret is provided.

```text
client_secret provided?
  ├── Yes → Client Credentials flow (existing behavior, 100% backward compatible)
  └── No  → Per-User Auth flow
              ├── Stored tokens exist and are valid? → Use refresh_token
              └── No stored tokens? → Interactive login (browser or headless)
```

--------------------------------

### Parallel and sequential tasks for User Story 1

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/003-per-user-auth/tasks.md

Task breakdown for User Story 1. T005 and T006 can run in parallel; T007-T012 are sequential dependencies. T009 is independent of the previous tasks.

```bash
# Launch independent infrastructure modules together:
Task T005: "Create callbackServer.ts — local HTTP server"
Task T006: "Implement PKCE + buildAuthorizeUrl in perUserAuth.ts"

# Then sequential flow (each depends on previous):
Task T007: "exchangeCodeForTokens in perUserAuth.ts" (needs T006)
Task T008: "openBrowser + performLogin in perUserAuth.ts" (needs T005, T007)
Task T009: "ClientCredentialsStrategy in oauth.ts" (independent of T005-T008)
Task T010: "PerUserAuthStrategy + factory in authStrategy.ts" (needs T008, T009)
Task T011: "Refactor mcpBridge.ts" (needs T010)
Task T012: "Update index.ts entry point" (needs T010, T011)
```

--------------------------------

### resources/list

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/001-apex-mcp-server/contracts/mcp-json-rpc.md

Lists all available resources exposed by the MCP server. This method is called by the client to discover the available resources.

```APIDOC
## resources/list

### Description
Lists all available resources exposed by the MCP server.

### Method
JSON-RPC

### Endpoint
resources/list

### Parameters
None

### Request Example
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "resources/list",
  "params": {}
}

### Response
#### Success Response
- **resources** (array) - List of resource objects
  - **uri** (string) - Resource URI
  - **name** (string) - Resource name
  - **description** (string) - Resource description
  - **mimeType** (string) - MIME type of the resource

#### Response Example
{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "resources": [
      {
        "uri": "salesforce://schema/Account",
        "name": "Account Schema",
        "description": "Field definitions for the Account object",
        "mimeType": "application/json"
      }
    ]
  }
}
```

--------------------------------

### tools/list Response

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/001-apex-mcp-server/contracts/mcp-json-rpc.md

Response containing the list of available tools with their input schemas.

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "tools": [
      {
        "name": "query_accounts",
        "description": "Search for Salesforce Account records",
        "inputSchema": {
          "type": "object",
          "properties": {
            "searchTerm": {
              "type": "string",
              "description": "Account name search term"
            },
            "limit": {
              "type": "integer",
              "description": "Maximum number of results"
            }
          },
          "required": ["searchTerm"]
        }
      }
    ]
  }
}
```

--------------------------------

### AccountSchemaResource implementation

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/001-apex-mcp-server/contracts/apex-public-api.md

Concrete implementation of McpResourceDefinition that reads Account object field metadata and returns it as a JSON resource. Sets uri, name, description, and mimeType in the constructor, and overrides read() to build a list of field maps and serialize them to JSON.

```apex
public class AccountSchemaResource extends McpResourceDefinition {

    public AccountSchemaResource() {
        this.uri = 'salesforce://schema/Account';
        this.name = 'Account Schema';
        this.description = 'Field definitions for the Account object';
        this.mimeType = 'application/json';
    }

    public override McpResourceResult read() {
        List<Map<String, String>> fields = new List<Map<String, String>>();
        for (Schema.SObjectField f : Account.SObjectType.getDescribe().fields.getMap().values()) {
            Schema.DescribeFieldResult dfr = f.getDescribe();
            fields.add(new Map<String, String>{
                'name' => dfr.getName(),
                'type' => dfr.getType().name(),
                'label' => dfr.getLabel()
            });
        }

        McpResourceResult result = new McpResourceResult();
        McpResourceContentItem item = new McpResourceContentItem();
        item.uri = this.uri;
        item.mimeType = this.mimeType;
        item.text = JSON.serialize(fields);
        result.contents = new List<McpResourceContentItem>{ item };
        return result;
    }
}
```

--------------------------------

### Claude Desktop MCP Client Configuration

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/001-apex-mcp-server/contracts/proxy-cli.md

Configures the MCP server for Claude Desktop in claude_desktop_config.json. Uses npx command with the same parameters as the CLI invocation.

```json
{
  "mcpServers": {
    "salesforce": {
      "command": "npx",
      "args": [
        "salesforce-mcp-lib",
        "--instance-url", "https://myorg.my.salesforce.com",
        "--client-id", "3MVG9...",
        "--client-secret", "ABC123...",
        "--endpoint", "/services/apexrest/mcp/v1"
      ]
    }
  }
}
```

--------------------------------

### Create release package version

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/CLAUDE.md

Creates a new package version for the npm or Salesforce 2GP package. Use the target org mcp-lib-devhub.

```bash
scripts/release-create.sh --target-org mcp-lib-devhub
```

--------------------------------

### Login for per-user auth

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/README.md

Performs a one-time login for per-user authentication. Requires an External Client App with Authorization Code + PKCE flow and the callback URL http://localhost:13338/oauth/callback.

```bash
npx salesforce-mcp-lib login \
  --instance-url https://your-org.my.salesforce.com \
  --client-id YOUR_CLIENT_ID
```

--------------------------------

### McpTextContent class

Source: https://github.com/damecek/salesforce-mcp-lib/blob/main/specs/001-apex-mcp-server/contracts/apex-public-api.md

Represents text content with a fixed type of 'text'. Constructor sets the text field.

```apex
public class McpTextContent {
    public String type = 'text';
    public String text;

    public McpTextContent(String text) {
        this.text = text;
    }
}
```
Tokens:
Raw