> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/en/mcp/maiagent-mcp.md).

# MaiAgent MCP: Let External AI Tools Operate the Platform

Use MaiAgent MCP to operate the platform from MCP-compatible AI tools such as Claude and Cursor: service endpoint and available tools, API Key and OAuth connections, verification, and troubleshooting

This page is for developers who want to let AI tools such as Claude Code, Claude Desktop, and Cursor operate the platform through MaiAgent MCP. It covers the service endpoint and available tools, API Key and OAuth connection setup, connection verification, and troubleshooting. For an introduction to MCP itself, see [MCP (Model Context Protocol)](/tech/en/mcp/mcp-model-context-protocol.md).

## <mark style="color:blue;">1. What Is MaiAgent MCP?</mark> <a href="#what-is-maiagent-mcp" id="what-is-maiagent-mcp"></a>

MaiAgent MCP is the official remote [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) service provided by MaiAgent. Add it to an MCP-compatible AI tool such as Claude Code, Claude Desktop, or Cursor to operate the MaiAgent platform directly using natural language, for example:

* “Create a customer service Agent for me using the Claude Sonnet model.”
* “List all the knowledge bases in my organization and upload this FAQ to the product knowledge base.”
* “Check yesterday's conversation records and summarize the questions users ask most often.”

| Item                 | Description                                                                                                                                  |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Service endpoint** | `https://mcp.maiagent.ai/mcp`                                                                                                                |
| **Transport**        | Streamable HTTP (remote connection, no local software installation required)                                                                 |
| **Authentication**   | API Key (in an HTTP header), or OAuth 2.1 (members sign in to MaiAgent in a browser and grant authorization)                                 |
| **Coverage**         | The full MaiAgent platform API: more than 300 endpoints for Agents, knowledge bases, conversations, tools, organization management, and more |

### Available Tools <a href="#available-tools" id="available-tools"></a>

Once connected, your AI tool receives the following six tools. The AI combines them automatically (search for an API, look up its specification, then execute it), so you do not need to memorize any API details:

| Tool                  | Purpose                                                                                                                        |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `debug_auth`          | Check whether authentication is configured correctly                                                                           |
| `list_api_categories` | List all API categories                                                                                                        |
| `search_apis`         | Search API endpoints by category or keyword                                                                                    |
| `get_api_details`     | Retrieve the full specification of a specific API (parameters, request body, and response format)                              |
| `call_api`            | Execute an API call                                                                                                            |
| `refresh_schema`      | Force a reload of the API list (use when a newly released API cannot be found; normally updates automatically every 5 minutes) |

#### Tool Input Formats <a href="#tool-schemas" id="tool-schemas"></a>

| Tool                                                  | Input Fields                                                                                                                      | Description                                                                                                                 |
| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `debug_auth`, `list_api_categories`, `refresh_schema` | None                                                                                                                              | —                                                                                                                           |
| `search_apis`                                         | `category` (string, optional), `search` (string, optional), `limit` (number, optional, default 20)                                | `search` accepts multiple space-separated terms; every term must match. Returns matching endpoints and their `operation_id` |
| `get_api_details`                                     | `operation_id` (string, required)                                                                                                 | Returns the endpoint's path, method, parameters, and request and response structures                                        |
| `call_api`                                            | `operation_id` (string, required), `path_params` (object, optional), `query_params` (object, optional), `body` (object, optional) | Executes the call; all three objects are flat “name → value” objects                                                        |

Rules for `call_api`:

* `operation_id` is the operationId shown for each endpoint in the API documentation, such as `v1KnowledgeBasesFilesList`.
* Keys in `path_params` correspond to the `{…}` names in the path (such as `knowledgeBasePk`). Values are URL-encoded before substitution. If a path parameter is missing, the call fails without sending a request.
* `query_params` becomes the query string directly. `body` is sent as JSON and is only needed for `POST`/`PUT`/`PATCH`.
* Authentication uses the API Key or OAuth token from the connection. You do not need to include a key in the parameters; permissions match the member's role.
* Responses larger than 50,000 bytes are truncated and marked as such. Use pagination parameters or filters to reduce the results.
* Errors returned by the API (`400`, `403`, `404`, etc.) are passed back to the AI unchanged. For the content format, see [API Conventions: Error Responses](https://docs.maiagent.ai/api/preparation/conventions#errors).

For example, to “list the PDF files in a particular knowledge base,” the AI calls the tools in this order:

```json
// 1. search_apis
{"search": "knowledge base files", "limit": 5}

// 2. get_api_details
{"operation_id": "v1KnowledgeBasesFilesList"}

// 3. call_api
{
  "operation_id": "v1KnowledgeBasesFilesList",
  "path_params": {"knowledgeBasePk": "550e8400-e29b-41d4-a716-446655440000"},
  "query_params": {"fileType": "pdf", "pageSize": 20}
}
```

{% hint style="info" %}
**Keep the direction clear**: This page explains how to “connect MaiAgent to **external** AI tools.” To do the reverse—attach other MCP tools to an Agent in MaiAgent—see [Create an MCP Tool](https://docs.maiagent.ai/build/tools/mcp-setup) in the user manual for admin console instructions. For the specification for turning your own system into an MCP Server, see [Self-Hosted MCP Server Integration Specification](/tech/en/mcp/self-hosted-mcp-server.md).
{% endhint %}

***

## <mark style="color:blue;">2. Prerequisites</mark> <a href="#prerequisites" id="prerequisites"></a>

Before you begin, choose an authentication method:

| Authentication Method | Best For                                                                                           | What You Need                                                                                                         |
| --------------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **API Key**           | Individuals or automation scripts; works with any MCP client that supports custom headers          | An API Key; see [Get an API Key](#get-api-key) below                                                                  |
| **OAuth**             | Multiple members connecting with their own accounts, without pasting keys into configuration files | An administrator must first create an OAuth application; see [Prepare an OAuth Application](#prepare-oauth-app) below |

Both methods grant the same permissions as the member's own role.

{% hint style="warning" %}
An API Key is bound to the **organization selected when the key is created**. All MCP operations apply to that organization. If you belong to multiple organizations, switch to the organization you want to operate in the upper-left corner of the admin console before creating a key. Each member can hold multiple keys. For management instructions, see [API Key Management](https://docs.maiagent.ai/org/developer/api-keys) in the user manual.
{% endhint %}

### Get an API Key <a href="#get-api-key" id="get-api-key"></a>

Sign in to the [MaiAgent Admin Console](https://admin.maiagent.ai), click your avatar in the upper-right corner → <mark style="color:blue;">Account</mark> → switch to the <mark style="color:blue;">API Keys</mark> tab → click <mark style="color:blue;">Create Key</mark>, then copy the generated API Key.

For details, see [Personal Account Settings: API Keys](https://docs.maiagent.ai/start/profile#api-keys) in the user manual. For administrators issuing keys on behalf of members, see [API Key Management](https://docs.maiagent.ai/org/developer/api-keys#create-api-key).

{% hint style="danger" %}
An API Key is displayed only once after creation. Copy it immediately and store it securely. An API Key represents your login identity. Do not share it with others or commit it to version control (git).
{% endhint %}

### Prepare an OAuth Application <a href="#prepare-oauth-app" id="prepare-oauth-app"></a>

Before connecting with OAuth, an administrator with “OAuth application management permissions” must create an application in the organization:

1. Go to <mark style="color:blue;">Organization Settings</mark> → <mark style="color:blue;">Organization Overview</mark> → <mark style="color:blue;">Management Actions</mark> → <mark style="color:blue;">OAuth Applications</mark>, then click <mark style="color:blue;">Create Application</mark>.
2. Set <mark style="color:blue;">Application Type</mark> to <mark style="color:blue;">Public</mark>.
3. In <mark style="color:blue;">Redirect URIs</mark>, enter the URL to which the MCP client redirects after authorization. It must exactly match the URL the client actually uses, such as `https://claude.ai/api/mcp/auth_callback` for Claude on the web. For Claude Code, see [Connect with OAuth](#setup-oauth) below.
4. After creation, provide the <mark style="color:blue;">Client ID</mark> to the members who will connect.

For the full procedure, see [OAuth Applications](https://docs.maiagent.ai/org/developer/oauth-applications#create-application) in the user manual.

{% hint style="warning" %}

* When connecting through OAuth, operations apply to **the organization that owns the application**. To operate in another organization, use an application created in that organization.
* The authorization page supports only Email and password sign-in. Members who use only SSO and do not have a login password cannot complete authorization. Use an API Key instead; see [Members Who Sign In Only with SSO](https://docs.maiagent.ai/org/developer/oauth-applications#sso-only-members).
  {% endhint %}

***

## <mark style="color:blue;">3. Connection Setup</mark> <a href="#setup" id="setup"></a>

Choose the setup method for your AI tool. The following examples use an API Key. Replace `<YOUR_API_KEY>` with the API Key you obtained in the prerequisites. To use OAuth instead, see [Connect with OAuth](#setup-oauth).

{% tabs %}
{% tab title="Claude Code" %}
Run in your terminal:

```bash
claude mcp add --transport http maiagent https://mcp.maiagent.ai/mcp \
  -s user \
  --header "Authorization: Api-Key <YOUR_API_KEY>"
```

`-s user` makes the connection available in all projects. To use it only in the current project, change this to `-s project` (the configuration is written to `.mcp.json` in the project root).

You can also edit `.mcp.json` manually:

```json
{
  "mcpServers": {
    "maiagent": {
      "type": "http",
      "url": "https://mcp.maiagent.ai/mcp",
      "headers": {
        "Authorization": "Api-Key <YOUR_API_KEY>"
      }
    }
  }
}
```

{% hint style="warning" %}
When using `-s project`, Claude Code asks whether you trust the project's MCP server on its first launch. Choose to approve it. If the directory containing `.mcp.json` is a git project, add `.mcp.json` to `.gitignore` to avoid committing your API Key.
{% endhint %}
{% endtab %}

{% tab title="Claude Desktop" %}
Edit the Claude Desktop configuration file (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`; Windows: `%APPDATA%\Claude\claude_desktop_config.json`) and add:

```json
{
  "mcpServers": {
    "maiagent": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.maiagent.ai/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Api-Key <YOUR_API_KEY>"
      }
    }
  }
}
```

Save the file and restart Claude Desktop.

{% hint style="info" %}
This method requires [Node.js](https://nodejs.org/) to be installed locally. The `Authorization` value is passed through `env` to prevent arguments containing spaces in the configuration file from being split incorrectly.
{% endhint %}
{% endtab %}

{% tab title="Cursor" %}
Edit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` in your project and add:

```json
{
  "mcpServers": {
    "maiagent": {
      "url": "https://mcp.maiagent.ai/mcp",
      "headers": {
        "Authorization": "Api-Key <YOUR_API_KEY>"
      }
    }
  }
}
```

After saving, go to <mark style="color:blue;">Cursor Settings</mark> → <mark style="color:blue;">MCP</mark> and confirm that `maiagent` is shown as connected.
{% endtab %}

{% tab title="Other MCP Tools" %}
Any MCP client that supports remote **Streamable HTTP** connections can use this service. Key settings:

| Setting                | Value                         |
| ---------------------- | ----------------------------- |
| Server URL             | `https://mcp.maiagent.ai/mcp` |
| Transport              | Streamable HTTP               |
| Header：`Authorization` | `Api-Key <YOUR_API_KEY>`      |
| {% endtab %}           |                               |
| {% endtabs %}          |                               |

### Connect with OAuth <a href="#setup-oauth" id="setup-oauth"></a>

When connecting with OAuth, **do not** include an `Authorization` header in the configuration. On the first connection, the MCP client receives a response from MaiAgent MCP requesting authorization, then opens a browser for you to sign in to MaiAgent. The authorization page shows the application name, its organization, and the currently signed-in account. Confirm these details and click “Authorize” to complete the process. The client then renews authorization automatically, so you do not need to sign in each time.

MaiAgent does not support dynamic client registration. The MCP client must allow you to enter a pre-created Client ID.

{% tabs %}
{% tab title="Claude Code" %}
Run in your terminal (`8765` can be replaced with any fixed port):

```bash
claude mcp add --transport http maiagent https://mcp.maiagent.ai/mcp \
  -s user \
  --client-id <CLIENT_ID> \
  --callback-port 8765
```

Register `http://localhost:8765/callback` in the OAuth application's <mark style="color:blue;">Redirect URIs</mark>. The port must match `--callback-port`.

After setup, enter `/mcp` in Claude Code, select `maiagent`, and follow the prompts to complete authorization in your browser.
{% endtab %}

{% tab title="Claude (Web/Desktop)" %}
Add a custom connector in Claude's connector settings: enter `https://mcp.maiagent.ai/mcp` as the URL, enter the OAuth Client ID in the advanced settings, then follow the prompts to connect and complete authorization.

Register `https://claude.ai/api/mcp/auth_callback` in the OAuth application's <mark style="color:blue;">Redirect URIs</mark>.
{% endtab %}

{% tab title="Other MCP Tools" %}
The client must support MCP OAuth authorization (authorization code + PKCE) and allow you to enter a pre-registered Client ID:

| Setting         | Value                                                                                     |
| --------------- | ----------------------------------------------------------------------------------------- |
| Server URL      | `https://mcp.maiagent.ai/mcp`                                                             |
| Transport       | Streamable HTTP                                                                           |
| OAuth Client ID | The OAuth application's Client ID                                                         |
| Redirect URI    | The callback URL actually used by the client; must be registered in the OAuth application |

For authorization server endpoints and protocol details, see [MaiAgent as an OAuth 2.1 Authorization Server](/tech/en/identity-and-access/maiagent-oauth-server.md).
{% endtab %}
{% endtabs %}

***

## <mark style="color:blue;">4. Verify the Connection</mark> <a href="#verify" id="verify"></a>

After setup, ask the AI in your AI tool to call `debug_auth` (for example, enter “Call maiagent's debug\_auth tool to check the connection”). You should see:

```json
{
  "has_auth_header": true,
  "auth_header_preview": "Api-Key xxxxxxxx...",
  "has_organization_id": false,
  "organization_id": null
}
```

If `has_auth_header` is `true`, the configured authentication is included. When connecting with OAuth, `auth_header_preview` starts with `Bearer`. It is normal for `organization_id` to show `null`: the organization to operate in is determined by the API Key or the organization that owns the OAuth application. To confirm that calls actually succeed, ask the AI to run a query next (for example, “List all my Agents”).

***

## <mark style="color:blue;">5. Start Using the Service</mark> <a href="#usage" id="usage"></a>

Once connected, give instructions directly in natural language. The AI automatically follows the `search_apis` → `get_api_details` → `call_api` flow to find and execute the appropriate API. Here are some useful examples:

* **Query**: “List all my Agents”, “Who are the members of this organization?”
* **Create**: “Create an Agent named ‘Product Support’ with the role instructions…”
* **Knowledge base**: “Create a new knowledge base and list the files currently in it.”
* **Operations**: “Check recent conversations for the ‘Product Support’ Agent and summarize common questions for me.”

{% hint style="warning" %}
Operations performed through MCP **have the same effect** as manual operations in the admin console (with the same permissions as your account). Before making changes such as deletions or modifications, ask the AI to explain the operations it is about to perform.
{% endhint %}

***

## <mark style="color:blue;">6. Troubleshooting</mark> <a href="#troubleshooting" id="troubleshooting"></a>

| Symptom                                                                                 | Possible Cause and Solution                                                                                                                                                                                                                                                                 |
| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| API calls return **401**                                                                | The API Key is incorrect, revoked, or disabled. Confirm the format is `Api-Key <YOUR_API_KEY>` (with one space between `Api-Key` and the key).                                                                                                                                              |
| Using an API Key, but the client asks you to sign in or says authentication is required | The configuration is not sending the `Authorization` header, so MaiAgent MCP asks the client to use OAuth instead. Check how the header is configured. To use OAuth, configure the Client ID as described in [Connect with OAuth](#setup-oauth).                                            |
| Redirect URI mismatch during OAuth authorization                                        | The client's callback URL does not match the one registered in the OAuth application. Confirm that the scheme, host, port, and path are exactly the same.                                                                                                                                   |
| Cannot sign in on the OAuth authorization page                                          | The authorization page supports only Email and password sign-in. Accounts that use only SSO should use an API Key instead.                                                                                                                                                                  |
| Operating in the wrong organization (expected Agents/knowledge bases are not found)     | An API Key is bound to the “organization selected when the key was created.” Switch to the correct organization, create a new key, and update the configuration file. OAuth operations apply to the organization that owns the application; use the Client ID for the correct organization. |
| The tool list is empty                                                                  | The connection was not established successfully. Restart the AI tool. In Claude Code, use `/mcp` to check the connection status.                                                                                                                                                            |
| Claude Code shows `Pending approval`                                                    | A project-level (`-s project`) MCP server must be trusted before it can connect. Start interactive Claude Code and follow the prompts to approve it.                                                                                                                                        |
| Permission errors when executing APIs                                                   | `call_api` executes using your identity and can only operate on resources your account has permission to access. Check your role permissions in that organization.                                                                                                                          |

{% hint style="info" %}
If you use a dedicated deployment (On-Premise) environment, the MCP service endpoint differs from the cloud version. Contact your MaiAgent service representative to confirm it.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/tech/en/mcp/maiagent-mcp.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.