Amplify MCP POC Proxy

A lightweight MCP server exposing two tools against a Salesforce org and BHA API. Deployed as AWS Lambda + API Gateway (HTTP API).

Tools

Tool	Description
find_candidate_by_name	SOQL query against Salesforce Contacts (Candidate record type) by name
send_candidate_to_screening	POSTs to BHA API with candidate Id, returns screening URL

---

Prerequisites

• Node.js 18+
• AWS CLI configured (aws configure)
• AWS SAM CLI (brew install aws-sam-cli or see docs)
• A Salesforce org with a Connected App configured for username/password OAuth
• BHA static API token

---

Local Setup

# 1. Install dependencies
npm install

# 2. Copy and fill in env vars
cp .env.example .env
# Edit .env with your real credentials

# 3. Run local smoke test against your SF org
node test-local.js "Smith"

The smoke test runs the full MCP handshake locally without deploying anything. If you see candidate names printed, the Salesforce connection is working.

---

Salesforce Connected App Setup

In your trial org (Setup > App Manager > New Connected App):

1. Enable OAuth Settings
2. Callback URL: https://login.salesforce.com/services/oauth2/success (not used but required)
3. Selected OAuth Scopes:
   • Access and manage your data (api)
   • Perform requests at any time (refresh_token, offline_access)
4. Enable Client Credentials Flow: checked
5. Save -- note the Consumer Key (Client ID) and Consumer Secret

Also ensure the running user has API access and can read Contact records.

---

Deploy to AWS

# 1. Build the deployment package
cd infra
sam build --template template.yaml --build-dir .aws-sam

# 2. Deploy (guided first time -- saves config to samconfig.toml)
sam deploy --guided \
  --template template.yaml \
  --stack-name amplify-mcp-poc \
  --capabilities CAPABILITY_IAM \
  --parameter-overrides \
    SfLoginUrl=https://test.salesforce.com \
    SfClientId=YOUR_CLIENT_ID \
    SfClientSecret=YOUR_CLIENT_SECRET \
    SfUsername=your.user@org.sandbox \
    SfPassword=yourpassword \
    SfSecurityToken=yourtoken \
    BhaApiBaseUrl=https://api.herefish.com/api/v1 \
    BhaApiToken=YOUR_BHA_TOKEN

# 3. Note the McpEndpoint output URL -- you'll need this for Claude Desktop

Subsequent deploys (after the first):

sam deploy --template template.yaml --stack-name amplify-mcp-poc

---

Wire into Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "amplify-poc": {
      "url": "https://YOUR_API_ID.execute-api.eu-west-1.amazonaws.com/mcp",
      "transport": "http"
    }
  }
}

Replace YOUR_API_ID with the value from the McpEndpoint SAM output. Restart Claude Desktop -- you should see find_candidate_by_name and send_candidate_to_screening appear as available tools.

---

Project Structure

amplify-mcp-proxy/
├── src/
│   ├── handler.js      # Lambda entry point -- MCP protocol router
│   ├── tools.js        # Tool definitions + handlers
│   ├── salesforce.js   # SF OAuth + SOQL query helper
│   └── bha.js          # BHA API client
├── infra/
│   └── template.yaml   # AWS SAM template
├── test-local.js       # Local smoke test
├── .env.example        # Environment variable template
└── package.json

---

Extending

To add a new tool:

1. Add the definition + handler function in src/tools.js
2. Register it in the TOOLS map at the bottom of that file
3. That's it -- tools/list and tools/call routing pick it up automatically

---

Notes

• The MCP session is stateless -- no server-side session storage. A fresh mcp-session-id is issued on every initialize call but no state is stored. This matches the production Bullhorn proxy pattern.

• The Salesforce access token is cached in Lambda memory for the lifetime of the execution context (warm invocations reuse it). Cold starts re-authenticate. This means one auth call per cold start, not per tool call.

• The BHA endpoint path (/screening) in src/bha.js may need adjusting to match your actual BHA API route. Check with your BHA/Herefish contact for the exact endpoint and payload shape.