Skip to content
AgentForceZone

.addMCP()

.addMCP()

Section titled “.addMCP()”

AgentForceAgent Optional Chainable

Add Model Context Protocol (MCP) servers to the agent’s configuration at runtime. MCP servers provide additional tools, resources, and capabilities that extend the agent beyond its built-in functionality. This method complements MCP servers configured in the AgentConfig.

Signature

Section titled “Signature”
addMCP(serverNameOrConfig: string | MCPServerConfig): AgentForceAgent

Parameters

Section titled “Parameters”
Parameter
Type
Default
Description
serverNameOrConfig
string | MCPServerConfig
N/A
Either a pre-configured MCP server name or a custom server configuration object

Returns

Section titled “Returns”

Returns the AgentForceAgent instance for method chaining.

Examples:

Section titled “Examples:”

Basic Usage

Section titled “Basic Usage”
import { AgentForceAgent } from '@agentforce/adk';


const agent = new AgentForceAgent({
  name: "FileAgent"
})
  .addMCP("filesystem")
  .addMCP("brave-search")
  .useLLM("ollama", "llama3")
  .prompt("List files and search for TypeScript info");


const response = await agent.output("text");

Advanced Configuration

Section titled “Advanced Configuration”
import { AgentForceAgent, type MCPServerConfig } from '@agentforce/adk';


// Custom MCP server with full configuration
const customServerConfig: MCPServerConfig = {
  name: "analytics-server",
  command: "node",
  args: ["./servers/analytics/index.js"],
  env: {
    DATABASE_URL: "postgresql://localhost:5432/analytics",
    API_KEY: process.env.ANALYTICS_API_KEY || ""
  },
  workingDirectory: "/opt/mcp-servers",
  timeout: 15000
};


const agent = new AgentForceAgent({
  name: "AnalyticsAgent"
})
  .addMCP(customServerConfig)
  .addMCP("filesystem") // Mix custom and pre-configured
  .useLLM("openrouter", "mistralai/mistral-small")
  .systemPrompt("You are a data analyst with access to analytics tools")
  .prompt("Generate weekly report");


const response = await agent.output("json");

Method Chaining

Section titled “Method Chaining”

The addMCP() method supports fluent chaining with other AgentForceAgent methods:

const agent = new AgentForceAgent({ name: "ChainedAgent" })
  .addMCP("github")
  .addMCP("filesystem")
  .useLLM("ollama", "gemma3:4b")
  .systemPrompt("You are a developer assistant")
  .prompt("Review my code and suggest improvements")
  .debug();


const response = await agent.output("text");

MCP Server Configuration

Section titled “MCP Server Configuration”

MCPServerConfig Interface

Section titled “MCPServerConfig Interface”
interface MCPServerConfig {
  name: string;                           // Unique server identifier
  type?: "local" | "sse" | "http";        // Server type (default: "local")
  command?: string;                       // Command to execute (required for local servers)
  args?: string[];                        // Command arguments (for local servers)
  url?: string;                           // Server URL (required for sse/http servers)
  env?: Record<string, string>;           // Environment variables
  workingDirectory?: string;              // Working directory (local servers only)
  timeout?: number;                       // Connection timeout in ms (default: 30000)
}

Server Types and Configuration Approaches

Section titled “Server Types and Configuration Approaches”
Approach
Input Type
Method
Description
Pre-configured
string
Simple
Use server names from your global MCP configuration. Supports both local and remote servers.
Custom Local
MCPServerConfig
Command-based
Define local server with command, args, and environment. Traditional MCP approach.
Custom Remote (SSE)
MCPServerConfig
URL-based
Define remote SSE server with URL. Modern cloud-based MCP servers.

Common MCP Servers

Section titled “Common MCP Servers”

File Operations

Section titled “File Operations”
Server Name
Category
Type
Description
filesystem
File I/O
Built-in
Read, write, and manage files and directories
git
Version Control
Built-in
Git operations, repository management

Web & APIs

Section titled “Web & APIs”
Server Name
Category
Type
Description
brave-search
Search
External
Web search capabilities via Brave Search API
github
Development
External
GitHub repository operations and API access

Database & Storage

Section titled “Database & Storage”
Server Name
Category
Type
Description
sqlite
Database
Built-in
SQLite database operations
postgresql
Database
External
PostgreSQL database access

Remote/Cloud Servers

Section titled “Remote/Cloud Servers”
Server Name
Category
Transport
Description
agentforce-adk-docs
Documentation
SSE
AgentForce ADK documentation server via GitMCP
custom-docs
Documentation
SSE/HTTP
Custom documentation servers via URL

Use Cases

Section titled “Use Cases”

Development Workflow

Servers: github, filesystem, git

Best for: Code review, documentation, repository management

Example: Analyze codebase, generate docs, create PRs

Data Analysis

Servers: sqlite, postgresql, filesystem

Best for: Data processing, report generation

Example: Query databases, generate reports, save results

Research & Content

Servers: brave-search, filesystem, github

Best for: Information gathering, content creation

Example: Research topics, compile information, save articles

System Administration

Servers: filesystem, git, custom servers

Best for: Server management, deployment, monitoring

Example: Deploy applications, manage configs, monitor logs

Configuration Examples

Section titled “Configuration Examples”

Environment-Based Configuration

Section titled “Environment-Based Configuration”
// Development environment
const devAgent = new AgentForceAgent({ name: "DevAgent" })
  .addMCP("filesystem")
  .addMCP("git")
  .useLLM("ollama", "phi4-mini:latest");


// Production environment
const prodAgent = new AgentForceAgent({ name: "ProdAgent" })
  .addMCP({
    name: "prod-db",
    command: "python",
    args: ["./mcp-servers/database.py"],
    env: {
      DATABASE_URL: process.env.PROD_DATABASE_URL,
      ENV: "production"
    },
    timeout: 30000
  })
  .addMCP("filesystem")
  .useLLM("openrouter", "mistralai/mistral-small");

Dynamic Server Addition

Section titled “Dynamic Server Addition”
const agent = new AgentForceAgent({ name: "DynamicAgent" });


// Add servers based on task requirements
const task = "analyze-database";


if (task.includes("database")) {
  agent.addMCP("postgresql");
}


if (task.includes("analyze")) {
  agent.addMCP("filesystem");
  agent.addMCP({
    name: "analytics",
    command: "python",
    args: ["./analytics-server.py"]
  });
}


const response = await agent
  .useLLM("ollama", "gemma3:4b")
  .prompt("Perform the requested analysis")
  .output("json");

Real-World Documentation Server

Section titled “Real-World Documentation Server”
// Connect to AgentForce ADK documentation via SSE
const docAgent = new AgentForceAgent({ name: "DocAgent" })
  .addMCP({
    name: "agentforce-adk-docs",
    type: "sse",
    url: "https://gitmcp.io/agentforcezone/agentforce-adk",
    timeout: 30000
  })
  .useLLM("openrouter", "anthropic/claude-3-haiku")
  .systemPrompt("You are an expert on AgentForce ADK with access to the complete documentation")
  .prompt("Explain the key architectural components and provide code examples");


const documentation = await docAgent.output("md");

Best Practices

Section titled “Best Practices”

✅ Effective MCP Usage

Section titled “✅ Effective MCP Usage”
// Group related servers together
const agent = new AgentForceAgent({ name: "WebDevAgent" })
  .addMCP("github")       // Repository access
  .addMCP("filesystem")   // File operations
  .addMCP("git")         // Version control
  .useLLM("ollama", "phi4-mini:latest");


// Use environment variables for sensitive config (local servers)
.addMCP({
  name: "api-server",
  type: "local",
  command: "node",
  args: ["./api-server.js"],
  env: {
    API_KEY: process.env.MCP_API_KEY,
    DATABASE_URL: process.env.MCP_DATABASE_URL
  }
});


// Configure remote SSE servers with appropriate timeouts
.addMCP({
  name: "docs-server",
  type: "sse",
  url: "https://gitmcp.io/your-org/your-repo",
  timeout: 30000  // 30 seconds for remote SSE servers
});


// Set longer timeouts for slow local services
.addMCP({
  name: "slow-service",
  type: "local",
  command: "python",
  args: ["./slow-server.py"],
  timeout: 60000  // 60 seconds for slow local services
});

❌ Common Issues

Section titled “❌ Common Issues”
// Empty server name
.addMCP("") // ❌ Server name cannot be empty


// Missing required configuration
.addMCP({
  name: "",  // ❌ Name is required
  command: "python"
});


// Duplicate server names (will be skipped)
.addMCP("filesystem")
.addMCP("filesystem") // ❌ Already configured, will be skipped


// Hardcoded sensitive values
.addMCP({
  name: "api-server",
  env: {
    API_KEY: "hardcoded-secret" // ❌ Use environment variables
  }
});

Error Handling

Section titled “Error Handling”
try {
  const agent = new AgentForceAgent({ name: "SafeAgent" })
    .addMCP("filesystem")
    .addMCP({
      name: "custom-server",
      command: "python",
      args: ["./non-existent-server.py"]
    })
    .useLLM("ollama", "gemma3:4b")
    .prompt("Test MCP integration");


  const response = await agent.output("text");
  console.log(response);
} catch (error) {
  console.error("MCP Error:", error.message);
  // Handle server connection issues, invalid configs, etc.
}

Integration with AgentConfig

Section titled “Integration with AgentConfig”

Combining Config and Runtime MCP

Section titled “Combining Config and Runtime MCP”
// Pre-configure some servers in AgentConfig
const config: AgentConfig = {
  name: "HybridAgent",
  mcps: ["filesystem", "git"],           // Pre-configured servers
  mcpConfig: "configs/agent.mcp.json"    // Agent-specific MCP config
};


// Add additional servers at runtime
const agent = new AgentForceAgent(config)
  .addMCP("github")                      // Add to existing MCPs
  .addMCP({                             // Custom server
    name: "task-specific",
    command: "node",
    args: ["./task-server.js"]
  })
  .useLLM("ollama", "phi4-mini:latest")
  .prompt("Use all available MCP tools");
Section titled “Related Methods”

See Also

Section titled “See Also”