MCP Servers

MCP (Model Context Protocol) allows your project to connect to external tool providers through a Streamable HTTP endpoint.
In ResearchX, MCP servers are configured per project and can provide additional tools for the chat agent.

What You Can Configure

• Add MCP servers in the project workspace asset panel (MCP tab)
• Enable or disable each server
• Set server name, display name, and MCP endpoint URL
• Test connectivity and discover available remote tools
• Optionally limit exposed tools with a whitelist (allowed_tools)
• Configure auth mode (none or bearer_token)
• Configure request stability parameters (connect_timeout_ms, request_timeout_ms)
• Configure whether discovered tools are exposed to chat

Where to Find It

1. Open project workspace
2. Open the Assets panel (Agents icon in the top area)
3. Switch to the MCP section
4. Click New to add a new MCP server

Add a Server

Fill in:

• name: short server identifier (e.g. linear)
• display_name: human readable name shown in UI (e.g. Linear)
• url: Streamable HTTP MCP endpoint (e.g. https://example.com/mcp)
• enabled: whether the server is active
• expose_tools_to_chat: whether MCP tools are exposed as chat tools

Authenticate the Server

You can choose:

• none: no auth header is added
• bearer_token: token is passed as Authorization: Bearer <token>

Test and Load Tools

After saving:

1. Select the server
2. Click Test & Load Tools
3. Confirm the server is reachable and check the discovered tool list
4. Save tool allowlist if needed

Discovery results are used to:

• verify connectivity before use
• show tool names, title, schema and description
• provide source for allowed_tools

Expose Rules

Chat uses MCP tools only when:

• the server is enabled
• expose_tools_to_chat is on
• the tool is allowed (if you set allowed_tools)

Safety and Confirmation Flow

Model tool calls to MCP are treated as tool execution and can be confirmed before running if configured.

• requires_user_confirmation (global): apply confirmation to all MCP tools
• confirmation_tools (tool-level): apply confirmation only to specific tools

When confirmation is required, requests enter the same tool permission flow used by other agent actions (visible in conversation controls).

Naming and Visibility

Each MCP tool is mapped to a stable tool name in chat:

• mcp_<server_name>_<tool_name>

This avoids conflicts with local actions/agents/tools.

Operations Reference

Common Actions

• Create server
• Update config
• Delete server
• Test connection
• Refresh discovered tools
• Open discovered tool details

Supported Transport

Current implementation uses streamable_http only.

Practical Tips

• Keep name concise and stable, because it affects generated tool names
• Use allowlist first when a remote service exposes many tools
• Start with smaller timeout values and increase if endpoint initialization is slow
• Disable unused servers to reduce tool noise in chat

FAQ

No tools appear after test

Possible causes:

• The server is not enabled
• URL is not reachable or not a Streamable HTTP MCP endpoint
• Timeout values are too low for the server to respond
• The server returns zero tools

Try:

• Re-check url and transport (currently only streamable_http is supported)
• Increase timeout and retest
• Confirm server logs or network policy for deny/timeout errors

Tool not shown in chat after discovery

Check these conditions:

• expose_tools_to_chat is enabled
• The server is enabled
• If allowed_tools is configured, the tool is included in the list

MCP call gets confirmation request

This is expected when:

• requires_user_confirmation is true, or
• the tool name appears in confirmation_tools

Approve via the normal tool permission flow in chat when you trust the action.

Permission/credential errors

For bearer_token servers, verify the token value is still valid and non-empty.