Salesforce AI Agent Server

A production-grade Model Context Protocol (MCP) server that gives Claude direct, structured access to Jira Cloud, Salesforce (Tooling + Metadata APIs), and n8n workflows.

Built for the Salesforce Developer AI Agent project — an automation pipeline that reads Jira stories, interprets Salesforce configuration requirements, and deploys metadata (custom fields, validation rules, etc.) directly into Salesforce.

---

Architecture

Claude Desktop / Claude Code / VS Code
           │  (stdio or SSE)
           ▼
  salesforce-ai-agent-mcp
  ┌───────────────────────────┐
  │  Tools (12 total)         │
  │  ├── Jira (4 tools)       │──► Jira Cloud REST API v3
  │  ├── Salesforce (6 tools) │──► Salesforce Tooling + Metadata APIs
  │  └── n8n (2 tools)        │──► n8n Webhook + REST API
  └───────────────────────────┘

---

Prerequisites

• Node.js ≥ 18
• npm ≥ 9
• A Jira Cloud account with API token
• A Salesforce org with a Connected App (OAuth 2.0)
• An n8n instance (optional, for workflow orchestration)

---

Installation

cd salesforce-ai-agent-mcp
npm install
npm run build

---

Configuration

Copy .env.example to .env and fill in your credentials:

cp .env.example .env

Jira

Variable	Description
JIRA_BASE_URL	e.g. https://your-org.atlassian.net
JIRA_EMAIL	Your Atlassian account email
JIRA_API_TOKEN	Generate at Atlassian API Tokens

Salesforce

You need a Connected App with the Username-Password OAuth flow enabled.

1. In Salesforce Setup → App Manager → New Connected App
2. Enable OAuth settings
3. Add scope: api, refresh_token
4. Copy Consumer Key → SF_CLIENT_ID
5. Copy Consumer Secret → SF_CLIENT_SECRET

Variable	Description
SF_LOGIN_URL	https://login.salesforce.com (prod) or https://test.salesforce.com (sandbox)
SF_CLIENT_ID	Connected App Consumer Key
SF_CLIENT_SECRET	Connected App Consumer Secret
SF_USERNAME	Your Salesforce username
SF_PASSWORD	Your Salesforce password
SF_SECURITY_TOKEN	Reset at Setup → Personal Information → Reset Security Token
SF_API_VERSION	API version, e.g. v61.0 (default)

n8n

Variable	Description
N8N_BASE_URL	Your n8n instance URL, e.g. https://your-n8n.com
N8N_API_KEY	Generate at n8n Settings → API → Create API Key

---

Usage

stdio mode (Claude Desktop / Claude Code / VS Code)

npm start
# or for development:
npm run dev

SSE mode (for remote/n8n integration)

npm run start:sse
# or for development:
npm run dev:sse

Endpoints available in SSE mode:

• GET http://localhost:3000/sse — clients connect here
• POST http://localhost:3000/messages?sessionId=<id> — clients send messages here
• GET http://localhost:3000/health — liveness probe

Override the port:

MCP_PORT=8080 npm run start:sse

---

Connecting to Claude Desktop

Add the following to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "salesforce-ai-agent": {
      "command": "node",
      "args": ["/absolute/path/to/salesforce-ai-agent-mcp/dist/index.js"],
      "env": {
        "JIRA_BASE_URL": "https://your-org.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your_token",
        "SF_LOGIN_URL": "https://login.salesforce.com",
        "SF_CLIENT_ID": "your_client_id",
        "SF_CLIENT_SECRET": "your_client_secret",
        "SF_USERNAME": "[email protected]",
        "SF_PASSWORD": "yourpassword",
        "SF_SECURITY_TOKEN": "yourSecurityToken",
        "N8N_BASE_URL": "https://your-n8n.com",
        "N8N_API_KEY": "your_n8n_api_key"
      }
    }
  }
}

---

Connecting to Claude Code (VS Code Extension)

Add to your VS Code settings.json (or via the MCP extension UI):

{
  "mcp.servers": {
    "salesforce-ai-agent": {
      "command": "node",
      "args": ["${workspaceFolder}/salesforce-ai-agent-mcp/dist/index.js"],
      "env": {
        "JIRA_BASE_URL": "https://your-org.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your_token",
        "SF_LOGIN_URL": "https://login.salesforce.com",
        "SF_CLIENT_ID": "your_client_id",
        "SF_CLIENT_SECRET": "your_client_secret",
        "SF_USERNAME": "[email protected]",
        "SF_PASSWORD": "yourpassword",
        "SF_SECURITY_TOKEN": "yourSecurityToken",
        "N8N_BASE_URL": "https://your-n8n.com",
        "N8N_API_KEY": "your_n8n_api_key"
      }
    }
  }
}

Alternatively, the mcp.json file at the root of this project is compatible with VS Code's MCP extension and will be auto-detected if placed in your workspace root.

---

Available Tools (12 total)

Jira Tools

jira_get_story

Fetch a Jira story by issue key. Returns summary, description, acceptance criteria, status, labels, and all custom fields.

issueKey: "SFDC-123"

jira_update_story_status

Transition a Jira story to a new workflow status.

issueKey: "SFDC-123"
targetStatus: "In Progress"   # must match an available transition

jira_post_comment

Post a comment to a Jira story (used by the AI agent to report results or ask for clarification).

issueKey: "SFDC-123"
body: "Deployed Customer_Tier__c field to Account. Deployment ID: 0Af..."

jira_search_stories

JQL-based story search.

jql: "label = \"sf-config\" AND status = \"To Do\" AND project = SFDC"
maxResults: 25

---

Salesforce Tools

salesforce_get_object_fields

Describe all fields on a Salesforce object.

objectName: "Account"

salesforce_create_custom_field

Create a custom field via the Tooling API.

objectName: "Account"
fieldLabel: "Customer Tier"
fieldApiName: "Customer_Tier"     # __c added automatically
fieldType: "Picklist"
picklistValues: ["Platinum", "Gold", "Silver", "Bronze"]
description: "Tier classification for account segmentation"

Lookup field example:

objectName: "Case"
fieldLabel: "Related Contract"
fieldApiName: "Related_Contract"
fieldType: "Lookup"
referenceTo: "Contract"

salesforce_create_validation_rule

Create a validation rule via the Tooling API.

objectName: "Account"
ruleName: "Require_Phone_For_Hot_Leads"
errorConditionFormula: "AND(Rating = \"Hot\", ISBLANK(Phone))"
errorMessage: "Phone number is required for Hot-rated accounts"
errorDisplayField: "Phone"
active: true

salesforce_deploy_metadata

Trigger a metadata deployment from a base64-encoded ZIP.

zipFile: "<base64-encoded-zip>"
checkOnly: false
testLevel: "RunLocalTests"
rollbackOnError: true

salesforce_get_deployment_status

Poll a deployment's status.

deploymentId: "0AfXXXXXXXXXXXXX"

salesforce_query

Execute SOQL for validation and verification.

soql: "SELECT Id, Name, Customer_Tier__c FROM Account WHERE Rating = 'Hot' LIMIT 10"

---

n8n Tools

n8n_trigger_workflow

Trigger an n8n workflow via webhook URL.

webhookUrl: "https://your-n8n.com/webhook/abc123"
payload: {
  "issueKey": "SFDC-123",
  "environment": "sandbox",
  "triggeredBy": "claude"
}

n8n_get_execution_status

Check the status of an n8n execution.

executionId: "12345"

---

Example AI Agent Workflow

You: "Process Jira story SFDC-456 and deploy the Salesforce configuration"

Claude:
1. jira_get_story(issueKey: "SFDC-456")
   → reads requirements: "Add Customer_Tier picklist to Account"

2. salesforce_get_object_fields(objectName: "Account")
   → confirms Customer_Tier__c doesn't exist yet

3. salesforce_create_custom_field(
     objectName: "Account",
     fieldLabel: "Customer Tier",
     fieldApiName: "Customer_Tier",
     fieldType: "Picklist",
     picklistValues: ["Platinum", "Gold", "Silver"]
   )
   → creates the field

4. salesforce_query(soql: "SELECT QualifiedApiName FROM FieldDefinition WHERE EntityDefinition.QualifiedApiName = 'Account' AND QualifiedApiName = 'Customer_Tier__c'")
   → verifies the field was created

5. jira_post_comment(
     issueKey: "SFDC-456",
     body: "✅ Customer_Tier__c picklist field created on Account object with values: Platinum, Gold, Silver."
   )

6. jira_update_story_status(issueKey: "SFDC-456", targetStatus: "Done")

---

Logging

All logs are written as structured JSON to stderr so they never interfere with the MCP stdio transport.

Control the log level via environment variable:

LOG_LEVEL=debug npm start    # debug | info | warn | error

---

Development

# Type-check only
npm run typecheck

# Build
npm run build

# Dev with hot reload (stdio)
npm run dev

# Dev with hot reload (SSE)
npm run dev:sse

---

Project Structure

salesforce-ai-agent-mcp/
├── src/
│   ├── index.ts              # Entry point — stdio & SSE transport setup
│   ├── server.ts             # McpServer creation & tool registration
│   ├── tools/
│   │   ├── jira.ts           # Jira tool definitions (4 tools)
│   │   ├── salesforce.ts     # Salesforce tool definitions (6 tools)
│   │   └── n8n.ts            # n8n tool definitions (2 tools)
│   ├── clients/
│   │   ├── jiraClient.ts     # Jira REST API v3 client
│   │   ├── salesforceClient.ts  # Salesforce Tooling/Metadata API + OAuth
│   │   ├── n8nClient.ts      # n8n webhook + REST API client
│   │   └── logger.ts         # Structured JSON logger (stderr)
│   └── types/
│       └── index.ts          # Shared TypeScript types
├── .env.example              # All required environment variables
├── mcp.json                  # VS Code MCP extension manifest
├── package.json
├── tsconfig.json
└── README.md