# Salesforce External MCP Server — AWS Hosted

A Python FastAPI MCP server deployed on AWS EC2 with nginx reverse proxy and Let's Encrypt SSL, registered as an External MCP Server inside Salesforce and called by an Agentforce Employee Agent ("A[...]

## Business Problem

Enterprises need Agentforce to reach external systems that aren't natively connected to Salesforce — legacy CRMs, loyalty platforms, custom order systems. This proves the pattern end to end: host[...]

## Architecture

![Architecture](demo/salesforce_external_mcp_architecture.png)

## How It Works

1. Agentforce Employee Agent ("AWS") has the MCP tools registered as available actions
2. User asks something like "What's the status of order 1001?"
3. Agent matches intent to the `get_order_status` tool
4. Salesforce authenticates via OAuth 2.0 Client Credentials against `/token`
5. Authenticated call routes through Named Credential to `/mcp`
6. nginx terminates SSL, reverse proxies to uvicorn on port 8000
7. FastAPI server processes the MCP JSON-RPC call, returns structured data
8. Agent composes a natural language reply

## Tools Exposed

| Tool | Input | Output |
|---|---|---|
| get_order_status | order_id | status, carrier, eta |
| check_loyalty_points | customer_id | points, tier |

## Salesforce Components

| Component | Type | Purpose |
|---|---|---|
| AWS | Agentforce Employee Agent | Calls the MCP tools as actions |
| NorthstarMCP | External Credential | OAuth 2.0 Client Credentials auth |
| NorthstarMCP | Named Credential | Secure endpoint URL |
| NorthstarMCP | External Service Registration | MCP tool registration |
| Agentforce Agent AWS Permissions | Permission Set | Grants agent access to MCP tools |

## OAuth 2.0 Configuration

| Field | Value |
|---|---|
| Flow | Client Credentials with Client Secret |
| Identity Provider URL | https://northstar-mcp.mooo.com/token |
| Scope | mcp.read |
| Named Credential URL | https://northstar-mcp.mooo.com/mcp |
| Principal | MCPAuthentication |

## Live Verification

```bash
curl https://northstar-mcp.mooo.com/
```
```json
{"status":"ok","info":"Dummy MCP server. POST /token for OAuth, POST /mcp for MCP JSON-RPC."}
```

Verified live on AWS EC2 — uvicorn process confirmed running, nginx confirmed listening on 443 with valid Let's Encrypt certificate.

## Problems Faced & How They Were Solved

| Problem | Root Cause | Fix |
|---|---|---|
| Salesforce couldn't reach localhost server | Not internet-accessible | Deployed to AWS EC2 with public domain |
| Salesforce rejecting HTTP connection | No SSL configured | nginx reverse proxy with Let's Encrypt via Certbot |
| Agent couldn't call the tools | Permission Set missing agent access | Created `Agentforce Agent AWS Permissions` with `agentAccesses` enabled |

## Prerequisites

- Salesforce org with Agentforce + MCP Server registration enabled
- Domain with DNS pointed to your server
- AWS EC2 instance, nginx, Certbot
- Python 3.9+, FastAPI, uvicorn

## Deployment

```bash
# Python server (on EC2)
pip3 install -r requirements.txt
python3 external_dummy_mcp_server.py

# SSL setup (one-time)
sudo certbot --nginx -d northstar-mcp.mooo.com

# Salesforce metadata
sf project deploy start --manifest package.xml
sf org assign permset --name Agentforce_Agent_AWS_Permissions
```

## Admin Configuration

| Step | Action |
|---|---|
| 1 | External Credential → add Client Secret for MCPAuthentication principal |
| 2 | Verify Named Credential URL points to /mcp endpoint |
| 3 | Confirm both tools show Active under MCP Servers |
| 4 | Add MCP tools to Agent → Actions |
| 5 | Activate the Agent |

## Demo

**Salesforce MCP Server registration**
![NorthstarMCP registration](demo/mcp1.jpg)

**Agent action configuration**
![Agent action](demo/mcp2.jpg)

**Live agent response**
![Agent response](demo/mcp3.jpg)

## Production Considerations

| Area | Current State | Production Fix |
|---|---|---|
| Data layer | In-memory Python dicts | Real database (RDS/PostgreSQL) |
| Credentials | Hardcoded in code | AWS Secrets Manager or env vars |
| Process management | Manual uvicorn process | systemd service for auto-restart |

## Key Insight

Most demos show an AI agent calling into Salesforce. This shows a Salesforce Agentforce agent calling OUT to an externally hosted MCP server with proper SSL and OAuth — proving Agentforce can i[...]

## Tech Stack

- Salesforce Agentforce (Employee Agent)
- External Service Registration (Model Context Protocol)
- Named Credentials + External Credentials (OAuth 2.0)
- Python FastAPI · AWS EC2 · nginx · Let's Encrypt