sf-agent-framework/sf-core/tasks/mcp-server-setup.md

AI Agent Orchestration Framework for Salesforce Development - Two-phase architecture with 70% context reduction

# MCP Server Setup Task

## Overview

Initialize and configure a Model Context Protocol (MCP) server for Salesforce
integration, enabling AI agents to interact with Salesforce data and services
through standardized interfaces.

## Prerequisites

- Salesforce org with API access enabled
- Connected App configured for OAuth
- Node.js 18+ or Python 3.8+ environment
- Understanding of MCP specification basics

## Task Steps

### 1. Choose Server Implementation

Select the appropriate MCP server type based on your use case:

```
┌─────────────────────────────────────┐
│  Which MCP server do you need?      │
├─────────────────────────────────────┤
│ • Salesforce DX Server              │
│   → Development operations          │
│ • REST API Server                   │
│   → Data access and manipulation    │
│ • MuleSoft Connector                │
│   → System integration              │
│ • Custom Server                     │
│   → Specialized functionality       │
└─────────────────────────────────────┘
```

### 2. Set Up Authentication

Configure OAuth 2.0 for secure Salesforce access:

```javascript
// Example OAuth configuration
const authConfig = {
  clientId: process.env.SF_CLIENT_ID,
  clientSecret: process.env.SF_CLIENT_SECRET,
  redirectUri: process.env.SF_REDIRECT_URI,
  authorizationUrl: 'https://login.salesforce.com/services/oauth2/authorize',
  tokenUrl: 'https://login.salesforce.com/services/oauth2/token',
  scopes: ['api', 'refresh_token', 'offline_access'],
};
```

### 3. Implement MCP Server

Create the server following MCP specification:

```javascript
// Basic MCP server structure
class SalesforceMCPServer {
  constructor(config) {
    this.config = config;
    this.connection = null;
  }

  async initialize() {
    // Set up Salesforce connection
    this.connection = await this.authenticate();

    // Register available tools
    this.registerTools();

    // Start MCP server
    this.startServer();
  }

  registerTools() {
    // Define available operations
    this.tools = {
      query: this.executeSOQL.bind(this),
      create: this.createRecord.bind(this),
      update: this.updateRecord.bind(this),
      delete: this.deleteRecord.bind(this),
    };
  }

  async executeSOQL(params) {
    // Implementation for SOQL queries
    const { query } = params;
    return await this.connection.query(query);
  }
}
```

### 4. Configure Security Policies

Implement enterprise-grade security:

```yaml
# mcp-security-policy.yaml
policies:
  authentication:
    type: oauth2
    required: true

  rateLimit:
    requestsPerMinute: 60
    requestsPerHour: 1000

  dataAccess:
    allowedObjects:
      - Account
      - Contact
      - Opportunity
    restrictedFields:
      - SSN__c
      - CreditCard__c

  audit:
    enabled: true
    retention: 90
```

### 5. Add to MCP Registry

Register your server for discovery:

```json
{
  "name": "salesforce-crm-server",
  "version": "1.0.0",
  "description": "MCP server for Salesforce CRM data access",
  "endpoint": "https://mcp.company.com/salesforce",
  "authentication": {
    "type": "oauth2",
    "authorizationUrl": "https://login.salesforce.com/services/oauth2/authorize"
  },
  "capabilities": ["query", "create", "update", "delete", "bulk"],
  "compliance": ["SOC2", "GDPR"]
}
```

### 6. Test Integration

Validate MCP server functionality:

```bash
# Test with MCP CLI
mcp test salesforce-crm-server

# Example test queries
mcp invoke salesforce-crm-server query --params '{"query": "SELECT Id, Name FROM Account LIMIT 10"}'
```

## Output Format

Your MCP server setup should produce:

1. **Server Implementation**
   - Complete MCP-compliant server code
   - Authentication configuration
   - Tool definitions and handlers

2. **Configuration Files**
   - Security policy YAML
   - Registry entry JSON
   - Environment variables template

3. **Documentation**
   - API reference for available tools
   - Authentication flow diagram
   - Deployment instructions

4. **Testing Suite**
   - Unit tests for each tool
   - Integration test scenarios
   - Performance benchmarks

## Quality Checklist

- [ ] OAuth authentication properly configured
- [ ] All CRUD operations implemented
- [ ] Security policies enforced
- [ ] Rate limiting active
- [ ] Audit logging functional
- [ ] Error handling comprehensive
- [ ] Documentation complete
- [ ] Tests passing

## Common Patterns

### Pattern 1: Read-Only Server

For scenarios requiring only data access:

```javascript
const readOnlyTools = ['query', 'describe', 'search'];
```

### Pattern 2: Admin Operations Server

For administrative tasks:

```javascript
const adminTools = ['createUser', 'assignPermissions', 'deployMetadata'];
```

### Pattern 3: Analytics Server

For reporting and analytics:

```javascript
const analyticsTools = ['runReport', 'getDashboard', 'exportData'];
```

## Troubleshooting

### Common Issues

1. **Authentication Failures**
   - Verify Connected App settings
   - Check OAuth scopes
   - Ensure refresh token handling

2. **Rate Limit Errors**
   - Implement exponential backoff
   - Use bulk operations where possible
   - Monitor API usage

3. **Data Access Issues**
   - Verify user permissions
   - Check field-level security
   - Validate SOQL syntax

## Next Steps

After completing MCP server setup:

1. Configure monitoring and alerting
2. Set up continuous deployment
3. Plan for Agentforce 3 migration
4. Implement multi-agent scenarios
5. Establish governance procedures