MCP Connector

The MCP (Model Context Protocol) connector bridges Agentcy with any MCP-compatible server, enabling dynamic tool discovery — tools are automatically discovered from the MCP server at runtime rather than being statically defined.

What is MCP?

The Model Context Protocol is an open standard for connecting AI assistants to external systems. MCP servers expose tools, resources, and prompts through a standardized JSON-RPC interface. Agentcy's MCP connector acts as an MCP client, connecting to any compliant server and making its tools available to the AI agent.

Configuration

stdio Transport

For MCP servers that run as local processes:

{
  "name": "File System MCP",
  "source_type": "mcp",
  "config": {
    "transport": "stdio",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"],
    "env": {}
  }
}

SSE Transport

For remote MCP servers exposed over HTTP with Server-Sent Events:

{
  "name": "Remote MCP Server",
  "source_type": "mcp",
  "config": {
    "transport": "sse",
    "url": "https://mcp.example.com/sse",
    "headers": {
      "Authorization": "Bearer your-token"
    }
  }
}

Streamable HTTP Transport

For MCP servers using the newer Streamable HTTP transport:

{
  "name": "HTTP MCP Server",
  "source_type": "mcp",
  "config": {
    "transport": "streamable_http",
    "url": "https://mcp.example.com/mcp",
    "headers": {
      "Authorization": "Bearer your-token"
    }
  }
}

Dynamic Tool Discovery

Unlike other connectors with fixed tool sets, the MCP connector discovers tools at runtime by calling the MCP server's tools/list method. This means:

• Tool count is dynamic — it depends on what the MCP server exposes
• Tool schemas are auto-mapped — MCP tool input schemas are converted to Agentcy's tool definition format
• Tools update automatically — when the MCP server adds or removes tools, Agentcy picks up the changes on the next connection

How It Works

1. Agentcy connects to the MCP server using the configured transport
2. Sends initialize to establish the session and negotiate capabilities
3. Calls tools/list to discover available tools and their schemas
4. Registers each MCP tool as an Agentcy connector tool
5. When the AI agent invokes a tool, Agentcy forwards the call via tools/call to the MCP server
6. The response is returned to the agent

┌──────────┐     ┌──────────┐     ┌──────────────┐
│ AI Agent │────▶│ Agentcy  │────▶│  MCP Server  │
│          │◀────│ (client) │◀────│  (any impl)  │
└──────────┘     └──────────┘     └──────────────┘
   tool call        tools/call        execute
   result           response          result

Example MCP Servers

The MCP ecosystem includes many community and official servers:

Server	Description	Install
@modelcontextprotocol/server-filesystem	File system read/write	npx -y @modelcontextprotocol/server-filesystem /path
@modelcontextprotocol/server-github	GitHub API access	npx -y @modelcontextprotocol/server-github
@modelcontextprotocol/server-postgres	PostgreSQL queries	npx -y @modelcontextprotocol/server-postgres postgres://...
@modelcontextprotocol/server-slack	Slack messaging	npx -y @modelcontextprotocol/server-slack
@modelcontextprotocol/server-puppeteer	Browser automation	npx -y @modelcontextprotocol/server-puppeteer

TIP

You can use any MCP server from the MCP Servers directory. If a tool already has a native Agentcy connector (like GitHub or PostgreSQL), the native connector is recommended for deeper integration and ETL support.

ETL Ingestion

The MCP connector also supports resource ingestion via the resources/list and resources/read MCP methods:

Nodes Created

Node Label	Properties	Source
MCPServer	name, transport, url_or_command, tool_count	Connection
MCPTool	name, description, input_schema	tools/list
MCPResource	uri, name, mime_type, description	resources/list

Relationships Created

Relationship	From	To
PROVIDES	MCPServer	MCPTool
EXPOSES	MCPServer	MCPResource

Configuration Reference

Field	Type	Default	Description
transport	string	required	Transport type: stdio, sse, or streamable_http
command	string	--	Command to run (stdio transport only)
args	string[]	[]	Arguments for the command (stdio transport only)
env	object	{}	Environment variables for the command (stdio transport only)
url	string	--	Server URL (sse and streamable_http transports)
headers	object	{}	HTTP headers for authentication (sse and streamable_http)
connection_timeout_secs	int	30	Timeout for initial connection
request_timeout_secs	int	60	Timeout for individual tool calls
auto_reconnect	bool	true	Automatically reconnect on connection loss

Security Considerations

MCP servers can execute arbitrary code. Consider the following when connecting MCP servers to Agentcy:

• Trust the server — only connect to MCP servers you control or trust
• Use the approval flow — enable connector approval so users must approve each MCP tool call
• Apply policies — use zero-trust policies to restrict which MCP tools can be executed
• Limit filesystem access — for stdio servers, scope file paths to specific directories
• Network isolation — run MCP servers in isolated network segments when possible

Troubleshooting

Error	Cause	Fix
Connection refused	MCP server is not running or URL is wrong	Verify the server is running and the URL/command is correct
Initialize timeout	Server took too long to respond to initialize	Increase connection_timeout_secs or check server health
Transport error	stdio process exited or HTTP connection dropped	Check server logs; enable auto_reconnect
Tool not found	Tool was removed from the MCP server	Refresh the tool list by reconnecting the source
Invalid tool arguments	Agent sent arguments that don't match the tool schema	The MCP server's tool schema may need updating