MCP Servers

Integrate external tools and services via the Model Context Protocol (MCP). Register MCP servers to extend agent capabilities with CRM integrations, database access, file operations, and more.

What is MCP?

The Model Context Protocol  (MCP) is an open standard developed by Anthropic that enables AI applications to connect with external data sources and tools. MCP servers expose tools, resources, and prompts that agents can use during conversations.

M3 Forge supports MCP through a dual-path architecture:

Getting Started

Accessing MCP Settings

Navigate to Settings → AI → MCP Servers to manage your MCP server registrations.

Registering an MCP Server

Choose transport type

MCP supports three transport mechanisms:

Transport	Use Case	Example
stdio	Local command-line tools	npx @playwright/mcp@latest
Streamable HTTP	Remote web services	https://api.example.com/mcp
SSE	Server-sent events (legacy)	https://legacy.example.com/sse

Configure connection

stdioStreamable HTTPSSE

stdio

stdio servers run as local processes spawned by the MCPExecutor.

Field	Description	Example
Command	Executable to run	npx, uvx, python
Arguments	Command-line args	["-y", "@playwright/mcp@latest"]
Environment	Environment variables	{"NODE_ENV": "production"}

{
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "@playwright/mcp@latest"]
}

Test the connection

Click Test Connection to verify connectivity. A successful test shows:

• Protocol version negotiated
• Server name and version
• Capabilities (tools, resources, prompts)

Discover tools

Click Discover Tools to fetch available tools from the server. Discovered tools are automatically synced to your Tool Library.

Server Configuration

Basic Settings

Authentication

For remote servers (Streamable HTTP, SSE):

Environment Variables (stdio)

For stdio servers, you can pass environment variables:

{
  "env": {
    "OPENAI_API_KEY": "{{$secrets.OPENAI_API_KEY}}",
    "DATABASE_URL": "postgres://..."
  }
}

Tool Library Integration

Discovered MCP tools are synced to the Tool Library as type: mcp tools:

• Automatic sync: Tools are created/updated on discovery
• Soft disable: Tools removed from server are disabled, not deleted
• Read-only: Synced tools cannot be edited directly — modify the MCP server instead
• Unique slugs: Format mcp--{server}--{tool}--{hash}

Assigning to Agents

MCP tools appear in the tool picker when configuring agents:

1. Navigate to Agents → [Your Agent] → Tools
2. Search for the MCP tool by name
3. Toggle to enable for this agent

Testing & Debugging

MCP Inspector

Before registering a server in M3 Forge, validate it with the official MCP Inspector :

# Test stdio server
npx @modelcontextprotocol/inspector npx @playwright/mcp@latest
 
# Test with arguments
npx @modelcontextprotocol/inspector npx @modelcontextprotocol/server-filesystem /path/to/dir
 
# Test Python MCP server
npx @modelcontextprotocol/inspector uvx mcp-server-git --repository ~/code/repo

The Inspector provides:

• Tools tab: List tools, test with inputs, view results
• Resources tab: Browse available data sources
• Prompts tab: Test prompt templates
• Notifications: Server logs and events

Connection Status

Each registered server shows connection status:

Common Issues

Debug Endpoints

Test MCP operations directly via the Gateway API:

# Test connection
curl -X POST http://localhost:51000/api/mcp/test \
  -H "Content-Type: application/json" \
  -d '{
    "transport": "stdio",
    "command": "npx",
    "args": ["-y", "@playwright/mcp@latest"],
    "timeout": 30
  }'
 
# Discover tools
curl -X POST http://localhost:51000/api/mcp/discover \
  -H "Content-Type: application/json" \
  -d '{
    "transport": "stdio",
    "command": "npx",
    "args": ["-y", "@playwright/mcp@latest"],
    "timeout": 30
  }'
 
# Call a tool
curl -X POST http://localhost:51000/api/mcp/call \
  -H "Content-Type: application/json" \
  -d '{
    "transport": "stdio",
    "command": "npx",
    "args": ["-y", "@playwright/mcp@latest"],
    "timeout": 30,
    "toolName": "browser_navigate",
    "toolArguments": {"url": "https://example.com"}
  }'

Security Considerations

Access Control

• Admin-only registration: Only administrators can register MCP servers
• Tool execution: Authenticated users can execute tools assigned to their agents
• Secret management: Credentials stored via SecretProvider, never in plaintext

stdio Security

stdio transport spawns processes on the MCPExecutor host. Security measures:

Prompt Injection Risks

MCP tools can be vectors for prompt injection:

• Review tool outputs: Attackers may embed instructions in data
• Validate inputs: Don’t pass untrusted user input directly to tools
• Limit sensitive access: Minimize MCP access to sensitive data sources

Best practices:

• Use official MCP servers from service providers
• Review tool definitions before enabling
• Monitor tool execution logs
• Implement user confirmation for destructive operations

Architecture Details

Dual-Path Model

Path 1: Agent Direct (runtime tool execution)

Agent → MCPTool → MCPSessionProvider → MCP Server

• Used for: Low-latency agent tool calls
• Session management: Persistent, ref-counted
• Pattern: BeeAI framework compatible

Path 2: Gateway HTTP API (management operations)

Studio → Gateway → MCPExecutor → MCP Server

• Used for: Test, discover, sync; external integrations
• Session management: Per-request
• Endpoints: /api/mcp/test, /api/mcp/discover, /api/mcp/call

Data Flow

API Reference

tRPC Endpoints

Gateway Endpoints

Best Practices

Server Registration

1. Test with Inspector first — Validate servers work before registering
2. Use descriptive names — “Playwright Browser” not “mcp-1”
3. Document purpose — Add description explaining what the server provides
4. Start disabled — Enable after verifying tools work correctly

Tool Management

1. Review before enabling — Check tool descriptions and schemas
2. Assign selectively — Only give agents the tools they need
3. Monitor usage — Watch for unexpected tool calls in logs
4. Re-discover periodically — Server tools may change over time

Production Deployment

1. Separate MCPExecutor — Run in isolated container with minimal privileges
2. Network policies — Restrict MCPExecutor egress to known MCP servers
3. Resource limits — Set CPU/memory limits to prevent runaway processes
4. Audit logging — Log all MCP operations for security review

Next Steps

• Gateways — Configure gateway connections
• Deployments — Monitor MCPExecutor deployment
• Registry — Discover registered services
• Debug — Troubleshoot MCP issues