MCP Server
Connect AI assistants to ByteChef using the Model Context Protocol
Coming soon
ByteChef exposes a Model Context Protocol (MCP) server that lets AI assistants - such as Claude, Cursor, and Windsurf - interact directly with your ByteChef instance to manage projects, workflows, and components.
This is the management server: its tools operate on ByteChef itself. To publish your own component actions and workflows as tools for an assistant to call, use MCP Servers in the Automation workspace instead - that is a different server, with a different URL and a different tool set.
The management server is on by default. An administrator turns it off with:
BYTECHEF_AI_MCP_SERVER_ENABLED=falseSee the AI MCP Server configuration reference.
Get Your MCP Server URL
The settings page presents the server URL inside ready-to-copy configuration snippets, grouped into per-client tabs - Claude, Cursor, Windsurf, and Other. Each snippet has a Refresh control that rotates the secret in the URL. The server speaks the Streamable HTTP transport only.
-
Open ByteChef and go to Settings → MCP Server
-
Copy the MCP server URL - it has the form:
https://<your-host>/api/management/<secret-key>/mcp
Keep this URL private. The secret key identifies your MCP server. You can regenerate it at any time from the same settings page; requests that still use the old secret are rejected with 401, even with a valid API key, until each client is updated.
The settings page - reading the URL, rotating it, and reading or changing Require authentication - is available to tenant admins only.
Whether the URL alone is enough to connect depends on Require authentication.
Authentication
The URL secret identifies the server. When the server has Require authentication enabled, a separate credential also authenticates the caller, and requests without a valid one are rejected with 401. Whether a credential is required is a setting on the server - see Require authentication below.
Require authentication
The management MCP server has a Require authentication toggle on its settings page:
- On - every request must carry a valid admin API key or a JWT from a trusted issuer; token-less requests get
401. This is the default for a server whose URL is generated for the first time. - Off - the URL secret alone is enough; requests are served without a credential, and an API key that is sent is ignored. A JWT that is sent is still validated when trusted issuers are configured. An anonymous caller can reach every workspace of the account.
Upgrading? A server configured before this setting existed has no stored value for it, and such a server reads as on: after the upgrade its clients must send a credential - see API key below for what they must send. Only an explicit off opens the endpoint to the URL secret alone, so an administrator who wants the previous behaviour switches Require authentication off.
Keep the URL secret private in both modes - it is the server's only protection when authentication is off.
API key (default)
Create an admin API key under Settings → Admin API Keys (an Enterprise Edition page) and send it with every request as a Bearer header:
Authorization: Bearer <your-api-key>It must be an Admin API key. A workspace API key - the kind under Settings → API Keys, for the automation public API - is rejected here with 401, because it is bound to a workspace while this server administers the whole account.
When the server requires authentication, the connection snippets below include this header. The API key is bound to an environment, and it must match the environment named in the X-ENVIRONMENT header (PRODUCTION when omitted; an unknown value is rejected with 401). The header only selects which key environment is accepted: tools that work inside a workspace take their own environment argument, which defaults to Development. A key that belongs to a deactivated user is rejected. Because the key is bound to your user account, the AI assistant acts with your permissions - and you can revoke a single client by deleting its key without touching the server URL or other clients.
JWT from a trusted issuer (optional)
The MCP endpoints can also accept JWTs issued by an identity provider you trust (Okta, Microsoft Entra, Keycloak, …). List each trusted issuer and its claim mapping under the BYTECHEF_OAUTH2_RESOURCE_SERVER_ISSUERS_* properties - see Environment Variables. JWT support stays dormant until at least one issuer is configured. A token from an issuer that is not listed is rejected with 401, and a token for this server must carry the mcp:management scope. API keys keep working alongside JWTs.
Connect an AI Assistant
Claude.ai (web)
Requires a Claude Pro subscription. claude.ai integrations cannot send custom headers, so they can only reach the server while Require authentication is off.
- Go to claude.ai/settings/integrations
- Click Add More
- Paste your MCP server URL and save
Claude Desktop
-
Open Claude Desktop
-
Go to Settings → Developer → Edit Config → Open
claude_desktop_config.json -
Add the following, replacing the URL with yours and
YOUR_API_KEYwith an admin API key:{ "mcpServers": { "ByteChef": { "command": "npx", "args": [ "-y", "mcp-remote", "https://<your-host>/api/management/<secret-key>/mcp", "--header", "Authorization: Bearer YOUR_API_KEY" ] } } } -
Save the file, then quit and restart Claude Desktop
Available Tools
The MCP server exposes the following tools to connected AI assistants.
Most tools work inside a workspace. When a call names no workspaceId and the account has more than one workspace, the tool returns a workspace_required error listing the workspaces, and the assistant retries with one of them; with a single workspace it is picked automatically.
Projects
| Tool | Description |
|---|---|
createProject | Create a new project |
updateProject | Update an existing project |
deleteProject | Delete a project |
getProject | Get project details |
listProjects | List all projects |
searchProjects | Search projects by keyword |
publishProject | Publish a project |
getProjectStatus | Get the current status of a project |
Workflows
| Tool | Description |
|---|---|
createProjectWorkflow | Create a new workflow in a project |
updateWorkflow | Update an existing workflow |
deleteWorkflow | Delete a workflow |
getWorkflow | Get workflow details |
listWorkflows | List the workflows of a project |
searchWorkflows | Search workflows by keyword |
saveWorkflowTestConnection | Select or create the connection a workflow uses when it is tested, in the current environment |
Components & Actions
| Tool | Description |
|---|---|
listComponents | List all available components |
getComponent | Get component details |
searchComponents | Search components by keyword |
listActions | List the actions of all components |
getAction | Get action details |
searchActions | Search actions by keyword |
getActionDefinition | Get the full definition of an action |
getOutputProperty | Get output property details |
getProperties | Get all properties of a trigger, action, or cluster element |
searchClusterElements | Find components that support a given cluster element type |
getClusterElement | Get cluster element details |
Triggers
| Tool | Description |
|---|---|
listTriggers | List the triggers of all components |
getTrigger | Get trigger details |
searchTriggers | Search triggers by keyword |
getTriggerDefinition | Get the full definition of a trigger |
Tasks
These tools address a task through a type argument - an action, a trigger, a task dispatcher, or, for some of them, a cluster element. listTasks and searchTasks cover actions, triggers and task dispatchers; getTaskDefinition does not accept cluster elements; getTaskDispatcherBuildInstructions takes no type.
| Tool | Description |
|---|---|
listTasks | List tasks in the project, optionally filtered by type |
getTask | Get details for one task of a given type |
searchTasks | Search across actions, triggers, and task dispatchers |
validateTask | Validate a task's structure and properties against its definition |
getTaskDefinition | Get a JSON template for configuring the task in a workflow |
getTaskDispatcherBuildInstructions | Get instructions for building with task dispatchers |
getTaskProperties | Get a task's properties, including nested ones |
getTaskOutputProperty | Get the structure of a task's output property |
Task dispatchers
| Tool | Description |
|---|---|
listTaskDispatchers | List all task dispatchers |
getTaskDispatcher | Get task dispatcher details |
searchTaskDispatchers | Search task dispatchers by keyword |
getTaskDispatcherDefinition | Get the full definition of a task dispatcher |
getTaskDispatcherProperties | Get a task dispatcher's properties |
getTaskDispatcherOutput | Get a task dispatcher's output property |
Editing a step in place
| Tool | Description |
|---|---|
updateScriptComponentCode | Replace the code of a script component task |
updateClusterElementTask | Update a cluster element attached to a task |
updateWorkflowRootProperties | Merge root-level properties - label, description, inputs, outputs - into a workflow definition |
Workspace resources
| Group | Tools |
|---|---|
| Skills | getAiSkills, getAiSkill, createAiSkill, updateAiSkill, updateAiSkillContent, getAiSkillFilePaths, getAiSkillFileContent, createAdditionalFilesInSkill, removeFileInSkill |
| MCP servers | listMcpServers, createMcpServer, updateMcpServer, createMcpProject, cloneMcpProject, listMcpProjectWorkflows |
| Deployments | listProjectDeployments, createProjectDeployment, updateProjectDeployment, deleteProjectDeployment, rollbackProjectDeployment, toggleProjectDeployment, promoteWorkflow |
| Knowledge bases | listKnowledgeBases, queryKnowledgeBase, createKnowledgeBase, addKnowledgeBaseDocument, deleteKnowledgeBaseDocument, cloneKnowledgeBase, deleteKnowledgeBase |
Delegate tools
Some capabilities are exposed as a single delegate tool that takes a natural-language instruction and calls the underlying operations itself, rather than as a flat list of tools like the ones above. Each accepts an optional workspaceId, auto-selected when the account has exactly one workspace.
| Tool | Description |
|---|---|
buildWorkflow | Designs, edits, debugs or explains a workflow |
importWorkflow | Converts a workflow definition from another tool (n8n, Make, Zapier, Workato, …) into an existing ByteChef workflow |
configureClusterElement | Designs, edits or explains cluster elements, such as an AI Agent's model, chat memory, RAG source, guardrails or tools |
writeScript | Writes, edits, debugs or explains the JavaScript, Python or Ruby code of a script task |
authorSkill | Lists, explains, creates or updates skills |
debugWorkflowExecution | Inspects or diagnoses a past workflow run and fixes the underlying workflow |
configureMcpServer | Writes the tool name, tool description and per-input fromAi(...) mapping of every workflow already attached to an MCP server; it never creates the server, attaches workflows or enables it |
How is this guide?
Last updated on
AI Providers
Activate LLM and AI providers once, per environment, and reuse them across Universal AI components, the Copilot, the Knowledge Base, and the AI Hub.
Custom Components
Extend the component catalog with your own - a JavaScript, Python, or Ruby source file or a Java jar, uploaded and enabled without forking the platform.