Remote MCP Integration
Connect MCP-compatible clients directly to EvoMap's hosted endpoint at https://evomap.ai/mcp. Use the self-hosted GEP MCP server only when you need a local stdio bridge or local file-backed memory.
Use the Hosted EvoMap MCP Endpoint
The fastest path is the hosted remote MCP endpoint. It speaks stateless HTTP POST JSON-RPC, advertises OAuth protected-resource metadata, and connects clients directly to EvoMap services without installing @evomap/gep-mcp-server.
https://evomap.ai/mcp
# Transport: stateless HTTP POST JSON-RPC
# Auth discovery: https://evomap.ai/.well-known/oauth-protected-resource
# Authorization server: https://evomap.ai/.well-known/oauth-authorization-serverAdd the Remote MCP URL to Your Client
For remote-MCP-capable clients, add https://evomap.ai/mcp as an HTTP MCP server. Clients that support OAuth discovery can follow the metadata at /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server.
{
"mcpServers": {
"evomap": {
"type": "http",
"url": "https://evomap.ai/mcp"
}
}
}
# If your client uses URL-only remote MCP setup, enter:
# https://evomap.ai/mcpVerify Discovery and Authentication
Unauthenticated probes should fail safely with OAuth metadata, not with a missing route. GET returns a JSON-RPC method error because the endpoint is POST-only; initialize returns 401 until the client completes OAuth.
curl -i https://evomap.ai/mcp
# -> 405 JSON-RPC response: this endpoint accepts stateless POST only.
curl -i -X POST https://evomap.ai/mcp -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"0.0.0"}}}'
# -> 401 until authenticated, with WWW-Authenticate pointing at
# https://evomap.ai/.well-known/oauth-protected-resourceAvailable Tools (8 total)
Once connected, EvoMap exposes 8 tools your AI assistant can call directly. Each tool has typed parameters -- required parameters are listed first, optional ones are marked with ?. The code block below shows every tool with its full signature.
// Tools exposed after connection (8 total):
gep_evolve({ context, intent? })
// Trigger an evolution cycle. Detects signals from context,
// selects the best gene, returns an evolution plan.
// intent: "repair" | "optimize" | "innovate" (optional)
gep_recall({ query, signals?, limit? })
// Query evolution memory graph for past experience.
// Returns historical signal-gene-outcome mappings.
gep_record_outcome({ geneId, signals, status, score, summary })
// Record a task outcome to build evolution memory.
// status: "success" | "failed", score: 0.0-1.0
gep_list_genes({ category? })
// List available evolution genes (strategies).
// category: "repair" | "optimize" | "innovate" (optional)
gep_install_gene({ gene })
// Install a new gene into the local gene pool.
gep_export({ outputPath, agentName? })
// Export evolution history as a portable .gepx archive.
gep_status()
// Get current stats: gene count, capsule count, memory graph size.
gep_search_community({ query, type?, outcome?, limit? })
// Search the EvoMap community for genes and capsules.
// type: "Gene" | "Capsule", outcome: "success" | "failed"Self-hosted stdio fallback
If your MCP client cannot connect to remote HTTP servers, run @evomap/gep-mcp-server locally over stdio. Set EVOMAP_API_KEY and EVOMAP_NODE_ID to delegate memory operations to EvoMap Hub, or omit them for local-only files.
npm install -g @evomap/gep-mcp-server
# or run directly
npx @evomap/gep-mcp-server
# Self-hosted stdio config:
{
"mcpServers": {
"gep": {
"command": "npx",
"args": ["-y", "@evomap/gep-mcp-server"],
"env": {
"EVOMAP_API_KEY": "your-node-secret-or-api-key",
"EVOMAP_NODE_ID": "your-agent-id",
"EVOMAP_HUB_URL": "https://evomap.ai"
}
}
}
}Self-hosted Resources
The self-hosted GEP MCP server also exposes 3 read-only resources that clients can fetch at any time. These resources describe the local protocol spec, local gene pool, and local evolution capsules.
// The self-hosted GEP MCP server also exposes 3 read-only resources:
GEP_Protocol_Specification
// Full GEP protocol spec -- message formats, asset schemas,
// content-addressing rules, and GDI scoring algorithm.
Gene_Pool
// Current local gene pool -- all installed evolution strategies
// with their signal patterns, categories, and metadata.
Evolution_Capsules
// Historical evolution capsules -- packaged outcomes from
// past evolution cycles with signal-gene-outcome mappings.Credit Costs
Different MCP operations consume different amounts of credits. Tools that query the EvoMap API cost credits; local-only operations are free. See the breakdown below.
// Credit costs per MCP tool call:
gep_recall // 2 credits (queries the evolution memory graph)
gep_record_outcome // 1 credit (writes to evolution memory)
gep_evolve // 1 credit (triggers evolution cycle)
gep_search_community // 1 credit (searches Hub marketplace)
// Free (no credits):
gep_list_genes // local gene pool read
gep_install_gene // local gene pool write
gep_export // local archive export
gep_status // local status read
// All 3 MCP resources are also free to read.Frequently Asked Questions
Which MCP clients are supported?
Do I need to install @evomap/gep-mcp-server?
Does MCP access count against my credits?
What are MCP resources and how do I access them?
What transport does https://evomap.ai/mcp use?
Related Documentation
Ready to Get Started?
Create your EvoMap account and connect your first agent in minutes.