MCP agents

"MCP agents" is used to register external AI platforms and control which ApiGo tools they can use through the admin-side MCP. It is a separate system from the conversational AI assistant on the AI Assistant page:

System	Location	Purpose
Conversational AI assistant	AI Assistant page	Built-in conversational entry point for operating the platform
MCP agents	Account Center → MCP	Credentials and tool authorization for external AI clients accessing the admin-side MCP

Agent list

Entry: Account Center → MCP.

Column	Description
Code	Agent code, i.e. the `{agentCode}` in the MCP address
Name	Display name of the agent
Type	WorkBuddy, Qianwen Office, Doubao, or Custom
Project	Project the agent belongs to
Status	Enabled / disabled
Last modified	Most recent update time
Actions	Tools, MCP configuration, Reset key, Delete

The list supports filtering by keyword and type. You can toggle the enabled state directly with a switch; once disabled, all MCP requests from that agent are rejected.

Create an agent

Creating an agent takes two steps:

1. Select a type

Type	Description	Default tools
WorkBuddy	General-purpose office agent	9 tools, including data source query, API query, log query, and API save/release/unpublish
Qianwen Office	Qianwen Office agent	4 tools for data source and API query
Doubao	Doubao agent	2 API query tools
Custom	Generic MCP client	No preset tools

The template only determines the initial tool set; after creation you can adjust it freely under "Tools".

2. Fill in the details

Field	Required	Description
Agent type	Yes	The type selected in the previous step; can be changed after creation
Project	—	Read-only, taken from the current project
Code	Yes	`^[a-z0-9_-]{3,64}$`, cannot be changed after creation, and is also used as the MCP path parameter
Name	Yes	Display name of the agent
Icon	No	Not available in the current UI
Description	No	Purpose description

Choose a code that reflects the caller and purpose, for example workbuddy-dev or ops-assistant.

Agent Key

After the agent is created, an Agent Key dialog appears:

The format is ak_ followed by a random string;
The server stores only the SHA-256 hash and an 8-character prefix; the plaintext is shown only once;
The dialog also provides an MCP configuration snippet for the corresponding platform;
If you forget the key or it leaks, click "Reset key" in the list and the old key is invalidated immediately.

The core structure of the configuration snippet:

{
  "mcpServers": {
    "ApiGo-Admin": {
      "type": "http",
      "url": "https://{your-gateway}/api/box/mcp/{agentCode}",
      "headers": {
        "X-Agent-Key": "{AgentKey}"
      }
    }
  }
}

For the admin-side MCP endpoint, protocol, and error codes, see MCP access.

Tool authorization

Click "Tools" in the list to open the tool drawer:

Tools are grouped by data source, API development, logs, groups, and other categories;
Each tool is marked as a write operation or not;
Supports searching by name/description, showing only selected tools, and selecting all tools in a category;
The footer shows the number of selected tools and the number of write tools;
Changes take effect in tools/list results immediately after saving.

The tool catalog contains 32 tools: 18 read-only and 14 write. Write tools trigger a second confirmation in the AI assistant; api_debug_invoke is also treated as a write operation because it may produce business side effects.

The tools actually available to an agent are also constrained by the creator's admin-side permissions. Even if a tool is bound, it does not appear in tools/list when the creator lacks the corresponding permission.

Permissions and isolation

The admin-side MCP permission model:

Agent dimension: only bound tools are exposed;
Creator dimension: the creator must still be an active user and have access to the project the agent belongs to;
Project dimension: all tool calls execute in the context of the agent's project and cannot access resources across projects;
State dimension: a disabled agent, a reset key, or an invalid creator all cause calls to fail.

An agent is therefore not a super account: it inherits the creator's permissions within its project and is further narrowed to the bound tool set.

Invocation and management

External clients use POST /api/box/mcp/{agentCode} with the X-Agent-Key header;
Supports initialize, tools/list, and tools/call;
Each successful authentication refreshes the last active time;
Call records are written to the agent call log, including the tool, parameter summary, result, and execution time;
Deleting an agent also deletes its tool bindings and key; the operation cannot be undone.

FAQ

Symptom	Cause	Resolution
Client reports a missing API key	`X-Agent-Key` is not sent	Add the Agent Key to the request headers
Agent does not exist	`agentCode` is wrong or the agent has been deleted	Check the code in the list
Agent is disabled	The status switch is off	Enable it in the list
Key is invalid	The key was reset or copied incompletely	Use the latest key
Tool list is empty	No tools are bound, or the creator lacks the corresponding permissions	Bind tools in the tool drawer and check the creator's permissions
Tool call reports no permission	The creator lost project access	Restore project permissions or recreate the agent

Agent list​

Create an agent​

1. Select a type​

2. Fill in the details​

Agent Key​

Tool authorization​

Permissions and isolation​

Invocation and management​

FAQ​

Related documentation​