Actions & MCP Integration
Relevant source files
The following files were used as context for generating this wiki page:
Actions in Onyx represent extended capabilities that allow Large Language Models (LLMs) to interact with external systems, perform searches, or execute code. A core component of this system is the integration of the Model Context Protocol (MCP), which provides a standardized way for LLMs to access knowledge bases, web search, and document management tools.
The integration architecture allows Onyx to act as both an MCP host (integrating external MCP servers) and an MCP server (exposing Onyx data to external clients like Claude Desktop). This dual-nature enables a flexible "tooling" ecosystem where agents can be equipped with specialized functions ranging from image generation to custom API interactions.
Sources: backend/onyx/mcp_server/README.md, web/refresh-pages/AgentEditorPage.tsx:490-550
Architecture Overview
Onyx implements a modular Actions system that categorizes tools into several types: Built-in tools (Search, Image Gen, Code Interpreter), OpenAPI actions (custom REST API integrations), and MCP-based tools.
MCP Server Component
The Onyx MCP server is built using FastMCP and runs as a sidecar to the main API server. It delegates authentication and access control logic to the primary Onyx API.
The MCP server provides specific tools to external clients, including search_indexed_documents, search_web, and open_urls.
Sources: backend/onyx/mcp_server/README.md:10-50
Action Integration Flow
When an agent is configured, administrators or users can enable specific Actions. For MCP-based tools, Onyx supports multiple authentication methods including API Keys and OAuth.
Tool Categories and Implementation
Onyx classifies Actions based on their underlying implementation and purpose.
1. Built-in Tools
These are core capabilities maintained within the Onyx ecosystem.
- Search: Semantic and keyword search across indexed company documents.
- Web Search: Public internet search using configured providers.
- Image Generation: Creating images via DALL-E or similar models.
- Code Interpreter: Execution of Python code in isolated sandboxes.
Sources: web/refresh-pages/AgentEditorPage.tsx:50-65, web/refresh-pages/AgentEditorPage.tsx:500-515
2. OpenAPI Actions
Onyx allows importing standard OpenAPI/Swagger specifications to turn REST API endpoints into LLM tools. These support OAuth configuration and persistent authentication status.
Sources: web/tests/e2e/admin/oauth_config/test_tool_oauth.spec.ts:100-150
3. MCP Integrated Tools
Tools provided by external MCP servers that follow the Model Context Protocol. Onyx tracks these tools via mcp_server_id and allows granular enabling/disabling of individual tools within a server.
Sources: web/refresh-pages/AgentEditorPage.tsx:515-535, web/tests/e2e/mcp/default-agent-mcp.spec.ts:200-220
Authentication and Security
Security for Actions is handled via several layers depending on the tool type.
MCP Authentication Methods
| Method | Description | Configuration Scope |
|---|---|---|
| API Key | Bearer token or static key passed in headers. | Admin-configured or per-user. |
| OAuth | Full OAuth2 flow requiring Client ID, Secret, and Scopes. | Global/Curator level. |
| Bearer Token | Validated and passed through on every request to the internal API. | Used by external MCP clients. |
Sources: backend/onyx/mcp_server/README.md:15-20, web/tests/e2e/mcp/mcp_oauth_flow.spec.ts:815-830, web/tests/e2e/mcp/default-agent-mcp.spec.ts:150-175
OAuth Flow Logic
For tools requiring OAuth (like certain MCP servers or OpenAPI actions), Onyx manages the redirect lifecycle.
- Admin triggers "Connect" in the UI.
- Onyx redirects to the Identity Provider (IdP).
- Upon callback, the
server_idis validated, and the tool state is updated to "Authenticated & Enabled".
Sources: web/tests/e2e/mcp/mcp_oauth_flow.spec.ts:390-450, web/tests/e2e/admin/oauth_config/test_tool_oauth.spec.ts:125-145
Configuration and Management
Agent Editor Integration
The AgentEditorPage provides a SimpleCollapsible section for Actions. It dynamically renders cards for each configured MCP server and OpenAPI action.
# Conceptual data structure for MCP tool state in the form
{
"mcp_server_1": {
"enabled": true,
"tool_101": true,
"tool_102": false
}
}
Sources: web/refresh-pages/AgentEditorPage.tsx:510-545, web/refresh-pages/AgentEditorPage.tsx:830-860
Key API Endpoints
| Endpoint | Method | Description |
|---|---|---|
/api/admin/mcp/server | POST | Register a new MCP server. |
/api/admin/mcp/server/{id}/db-tools | GET | Retrieve tools currently stored in DB for a server. |
/api/mcp/oauth/status | GET | Check the OAuth authentication status for MCP servers. |
/api/admin/persona/upload-image | POST | Upload an icon/avatar for an agent. |
Sources: web/tests/e2e/mcp/default-agent-mcp.spec.ts:145, web/tests/e2e/mcp/mcp_oauth_flow.spec.ts:645, web/refresh-pages/AgentEditorPage.tsx:120
Summary
The Actions & MCP Integration system is a cornerstone of Onyx's extensibility. By supporting the Model Context Protocol, Onyx allows developers to plug in specialized knowledge and functional tools without rewriting core agent logic. The system balances ease of use—via auto-discovery of MCP tools—with enterprise requirements for secure OAuth-based authentication and granular permission management at the agent level.