MCP Tools Routing FAQ & Answers

Content array contains typed content items. Format: content: [{type: 'text', text: string}, {type: 'image', data: base64, mimeType: string}, {type: 'resource', uri: string, mimeType?: string}]. Text type: Use for strings, JSON, logs. Image type: Use data: field with base64-encoded image, specify mimeType (image/png, image/jpeg). Resource type: Reference external URIs. Multiple items allowed in single response. Example multi-type: [{type: 'text', text: 'Results:'}, {type: 'image', data: base64Data, mimeType: 'image/png'}]. Clients render based on type.

Use specific paths like /mcp for production deployments. Root path (/) works but causes conflicts when hosting multiple services on same domain. Best practice: /mcp for single MCP server, /mcp-service1, /mcp-service2 for multiple servers. Example nginx config: location /mcp {proxy_pass http://localhost:3001/mcp;}. Client connects to https://domain.com/mcp. This enables: Multiple MCP servers per domain, coexistence with REST APIs on same host, clear service boundaries. Only use root (/) for development or dedicated MCP-only domains.

Specific paths prevent routing conflicts and enable multi-service deployments. Problems with root (/): Cannot host multiple MCP servers, conflicts with web UI/API routes, unclear service boundaries. Benefits of /mcp path: Host multiple MCPs (/mcp-discovery, /mcp-knowledge), serve web UI on root alongside MCP, explicit service identification in logs, easier nginx/proxy configuration. Production pattern: Frontend on /, REST API on /api, MCP on /mcp. Example: agentskb.com (website) + api.agentskb.com/mcp (MCP server) OR single domain with agentskb.com/, /api, /mcp.

Use nginx path-based routing to different backend ports. Pattern: Server1 on port 3001 at /mcp-service1, Server2 on port 3002 at /mcp-service2. nginx config: location /mcp-service1 {proxy_pass http://localhost:3001/mcp; proxy_http_version 1.1; proxy_set_header Mcp-Session-Id $http_mcp_session_id;} location /mcp-service2 {proxy_pass http://localhost:3002/mcp;}. Each MCP server internally uses /mcp route. Client connects: https://domain.com/mcp-service1, https://domain.com/mcp-service2. Enables: Discovery service + Knowledge service on same domain, independent scaling, separate process management.

Roots define filesystem/URI boundaries that clients grant to MCP servers. Client-provided, not server-declared. Servers request roots via roots/list, clients respond with accessible paths. Format: [{uri: 'file:///workspace', name: 'Project Files'}] using RFC 8089 file URI scheme. Server capabilities: {roots: {listChanged: true}} enables notifications when roots change. Security model: Client-side permissions with user approval required. Servers MUST respect boundaries—cannot access outside granted roots. Use cases: File tools (limit to project directory), API tools (define endpoint scope), database tools (specify schemas). Pattern: Narrow roots for security, broad roots for convenience. Example workspace detection: auto-detect from .git, package.json, or explicit user selection via UI picker.

No, group related operations into semantic tools. Anti-pattern: create_user, update_user, delete_user, get_user as separate tools (too granular). Better pattern: manage_user tool with action parameter. Tool design: One tool per agent capability, not per API endpoint. Example: Instead of 5 CRUD tools, create search_entities (read), update_entity (write). Parameters handle variations. Good tool: discover_similar(slug, limit, minScore) - encapsulates similarity search. Bad: discover_anime, discover_manga, discover_games - repetitive. Target: 5-15 tools per MCP server. Too many tools (50+) overwhelm LLMs, too few (1-2) limit capabilities. Group by agent intent, not API structure.

Tool names must match ^[a-zA-Z0-9_-]{1,64}$. Rules: 1-64 characters, alphanumeric + underscore + hyphen only, no spaces or special chars. Valid: search_entities, discover-similar, getUserData, fetch_data_v2. Invalid: 'search entities' (space), 'fetch/data' (slash), 'get.user' (dot), '' (empty). Convention: Use snake_case (search_entities) or kebab-case (search-entities) for consistency. Avoid camelCase as it's less readable in tool lists. Keep descriptive: search_by_tags better than search3. Prefix with domain for multi-domain servers: kb_search, graph_discover. Tool names appear in LLM prompts - make them self-explanatory.