Synapse AI — Execution Server

Node.js + TypeScript server that runs Synapse AI agent graphs. Salesforce stores config and audit; this server does all AI inference and MCP tool execution so Apex stays inside governor limits.

Architecture

   Salesforce org                                Synapse AI server (this repo)
 ┌───────────────────┐    JWT-signed HTTPS    ┌─────────────────────────────┐
 │ AgentBuilder UI   │  ────────────────────▶ │ POST /agent/execute         │
 │ AgentRunner.cls   │     Named Credential   │   ├ verify JWT              │
 │ Trigger handlers  │     "Agent_Platform"   │   ├ load AgentDefinition    │
 │                   │ ◀── Platform Event ─── │   ├ walk graph              │
 │ AgentExecution__c │   AgentExecutionResult │   ├ exec nodes              │
 └───────────────────┘                        │   │   ├ claude (ai-models)  │
                                              │   │   ├ get/update record  │
                                              │   │   └ if/else, loop ...  │
                                              │   └ publish result event   │
                                              └─────────────────────────────┘

Prerequisites

• Node.js ≥ 20 (the SDK and tsx need modern Node)
• A Salesforce dev/sandbox org with the Synapse AI metadata deployed
• An Anthropic API key (sk-ant-...)
• ngrok (or any tunneling tool) for local dev, OR a public host (Heroku, Fly.io, AWS Lambda + API Gateway, etc.) for production
• openssl for generating the JWT secret and SF Connected App cert

1. Install

cd server
npm install

2. Configure environment

cp .env.example .env

Generate a JWT secret:

openssl rand -hex 32
# paste the output as JWT_SECRET in .env

Set ANTHROPIC_API_KEY to your key from https://console.anthropic.com/.

The Salesforce values (SF_CLIENT_ID, SF_USERNAME, SF_PRIVATE_KEY_PATH) come from step 4.

3. Run the server

Dev mode (auto-reload):

npm run dev

Production:

npm run build
npm start

You should see synapse_ai_server_started in the log and GET /health returning {"status":"ok"}.

4. Wire Salesforce → server

4a. Expose the server publicly (dev)

ngrok http 3000
# → https://abc123.ngrok-free.app

In Setup → Named Credentials → Agent Platform:

• Endpoint: paste the ngrok URL (no trailing slash)
• Save

4b. Make Salesforce sign requests with your JWT secret

Salesforce's Named Credential alone can send an unsigned bearer header. To get HMAC-signed JWTs that this server can verify, customers usually:

Option A — Use an External Credential (recommended for production)

1. Setup → External Credentials → New
2. Authentication Protocol: Custom
3. Authentication Parameters: add JwtSecret = the same hex string in JWT_SECRET
4. Link the External Credential to the Agent_Platform Named Credential
5. Write a small HttpCalloutAction Apex class (or use Flow HTTP Callouts) that mints a JWT in Apex using Crypto.generateMac('HmacSHA256', ...) and sets Authorization: Bearer <jwt> on the request

Option B — Quick dev shortcut

In AgentBuilderController.executeAgent and AgentRunner.callExternalEngine, sign the JWT inline before the callout:

String jwt = mintHs256Jwt(new Map<String,Object>{
    'orgId' => UserInfo.getOrganizationId(),
    'userId' => UserInfo.getUserId(),
    'agentApiName' => agentApiName,
    'iat' => DateTime.now().getTime()/1000,
    'exp' => (DateTime.now().getTime()/1000) + 300  // 5 min
}, jwtSecretFromCustomMetadata());
req.setHeader('Authorization', 'Bearer ' + jwt);

Where mintHs256Jwt does the base64url(header) + base64url(payload) + HMAC-SHA256 signature. We can add this helper in a follow-up commit.

4c. Configure the server's own SF connection (for callbacks + MCP)

The server logs in to Salesforce as itself (a System Integration user) to load agent definitions and write audit logs back. Use JWT Bearer Token Flow:

1. openssl req -x509 -nodes -newkey rsa:2048 -keyout keys/server.key -out keys/server.crt -days 365 -subj "/CN=SynapseAIServer"
2. Setup → App Manager → New Connected App:
   • Enable OAuth Settings
   • Check Use digital signatures, upload server.crt
   • OAuth Scopes: api, refresh_token, offline_access
   • Save
3. Copy the Consumer Key into SF_CLIENT_ID
4. In Setup → Manage Apps → the new app → Manage → Permitted Users: Admin approved, then pre-authorize a System Integration user via a permission set
5. Set SF_USERNAME to that user's username
6. SF_PRIVATE_KEY_PATH=./keys/server.key

5. End-to-end test

1. Deploy SF metadata: sf project deploy start --target-org <your-org>
2. Assign the permission set: sf org assign permset --name AgentBuilderUser
3. Open the Synapse AI app from the App Launcher
4. Click + New Agent, drag a Record trigger → Claude AI → End, save with name "Lead Qualifier" and ApiName lead_qualifier, set Status to Active
5. From the Test Runner: enter a Lead ID, click Run agent
6. Watch the server log — you should see claude_call_complete with cache_creation on the first call, then cache_read > 0 on subsequent calls (proving the knowledge-base prompt cache is working)

Project layout

src/
├── index.ts                 Express entry, mounts routers, error handler
├── config.ts                Typed env config
├── logger.ts                pino logger
├── types.ts                 Shared types (AgentDefinition, NodeResult, ...)
├── auth/jwt.ts              JWT verify middleware
├── routes/
│   ├── agent.routes.ts      POST /agent/execute, GET /agent/status/:id
│   └── health.routes.ts     GET /health
├── orchestrator/
│   ├── engine.ts            runAgent() — BFS walks the graph
│   ├── context.ts           ExecutionContext + {!var} interpolation
│   └── graph.ts             Builds adjacency map from CanvasJson__c
├── nodes/
│   ├── registry.ts          subType → executor lookup
│   ├── trigger.ts           record / schedule / webhook / platform_event
│   ├── ai.ts                claude (real), gpt4 / einstein / sentiment (stubs)
│   ├── action.ts            get/update/create/query record, create_task, post_chatter
│   ├── channel.ts           outlook / gmail / sendgrid / twilio / slack / teams (stubs)
│   ├── logic.ts             if_else (real), loop / wait / approval
│   └── end.ts
├── mcp/
│   ├── registry.ts          MCP server name lookup
│   └── servers/
│       ├── ai-models.ts     Claude integration (Opus 4.7 + adaptive thinking + prompt caching)
│       └── salesforce-crm.ts  jsforce-backed CRUD + SOQL
└── salesforce/
    ├── client.ts            jsforce JWT-bearer login, loadAgentDefinition()
    └── callback.ts          Publishes AgentExecutionResult__e events

Adding a new node type

1. Create or pick an MCP server under src/mcp/servers/
2. Write the executor in src/nodes/<category>.ts and call register('your_subtype', execFn)
3. Import the file in src/orchestrator/engine.ts (side-effect import — runs the register() call)
4. Add the field schema to agentPropertiesPanel.js so the canvas UI shows config inputs
5. Add an entry to NODE_PALETTE in agentCanvas.js so the node appears in the palette

Adding a new MCP server

1. Create src/mcp/servers/<name>.ts and export typed functions (callX, queryY, ...)
2. Add <name> to the MCP_SERVERS const in src/mcp/registry.ts
3. Reference the server from node executors via direct function imports

When the official MCP wire protocol stabilizes, swap the direct imports for an MCP client that dispatches by node.mcpServer + node.mcpTool — the registry is already shaped for this.

Deploying to production

• Heroku/Fly.io: works out of the box. Set the same env vars in the dashboard. Use npm run build && npm start as the start command.
• AWS Lambda + API Gateway: wrap the express app with serverless-http — note that JWT-bearer SF logins should be cached in a warm container or pulled from Secrets Manager.
• Containerized: a 2-stage Dockerfile (build with full deps, run with node:20-alpine) is the standard path.

Cost considerations

• The first call to a given agent writes the knowledge-base prompt cache (~1.25× input cost)
• Every call after that reads it (~0.1× input cost) — this is why we put the KB at the top of system with cache_control
• Adaptive thinking + effort: "high" on Opus 4.7 gives the best quality; drop to medium if you need lower per-call cost
• For latency-sensitive use cases, swap claude-opus-4-7 → claude-haiku-4-5 per node — the UI exposes this in the properties panel