MCP

MCP tools are server-side proxied by OpenAI. The engine passes MCP configs in the tools array, OpenAI executes them remotely, and results flow into responses automatically. No local execution or special handling needed.

Configuration

Add MCP servers to your plugin options via the mcpServers array:

export default {
	mcpServers: [
		{
			type: 'mcp',
			server_label: 'context7',
			server_url: 'https://mcp.context7.com/mcp',
			headers: { CONTEXT7_API_KEY: process.env.CONTEXT7_API_KEY ?? '' },
			allowed_tools: ['resolve-library-id', 'get-library-docs'],
			require_approval: 'never'
		}
	]
}

export default {
	mcpServers: [
		{
			type: 'mcp',
			server_label: 'context7',
			server_url: 'https://mcp.context7.com/mcp',
			headers: { CONTEXT7_API_KEY: process.env.CONTEXT7_API_KEY ?? '' },
			allowed_tools: ['resolve-library-id', 'get-library-docs'],
			require_approval: 'never'
		}
	]
}

You can add multiple MCP servers. Each one must have a unique server_label.

MCPTool fields

Error handling

Configure resilience for MCP tool failures via the mcp option:

export default {
	mcp: {
		gracefulDegradation: true,
		extraRetries: 1,
		baseDelayMs: 500,
		maxDelayMs: 2000
	}
}

export default {
	mcp: {
		gracefulDegradation: true,
		extraRetries: 1,
		baseDelayMs: 500,
		maxDelayMs: 2000
	}
}

Graceful degradation

When MCP tools cause API failures, the engine follows this sequence:

1. Extra retries with exponential backoff (configurable via extraRetries, baseDelayMs, maxDelayMs).
2. If retries still fail and gracefulDegradation is true, MCP tools are removed from the request and the engine retries without them.
3. A status note is injected into the system prompt telling the AI that certain external tools were unavailable.
4. The degradedMcpServers array in ReplyHookContext lists the affected server labels, so reply hooks can apply custom handling.

This prevents entire requests from failing due to transient MCP server issues while keeping the AI transparent about tool unavailability.

Accessing MCP data

Retrieve configured MCP servers at runtime with AI.getMCPServers():

import { AI } from '@robojs/ai'

export default () => {
	const servers = AI.getMCPServers()
	return `${servers.length} MCP server(s) configured.`
}

import { AI } from '@robojs/ai'

export default () => {
	const servers = AI.getMCPServers()
	return `${servers.length} MCP server(s) configured.`
}

Validation

During init(), the engine validates every MCP config:

• Checks for required fields (type, server_label, server_url).
• Detects duplicate server_label values.
• Validates headers is an object when provided.

Invalid configs are logged with a warning and skipped. The engine continues initializing with the remaining valid servers.

Limitations

MCP tools are only available in standard chat context (the worker path). They aren't available in realtime voice sessions.

Next steps