> 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/remote-mcp.md).
# Remote MCP Service Overview
The concept of Remote MCP services and how MaiAgent connects to hosted services such as Composio and Zapier and self-hosted MCP servers: transport, authentication, tool scope, timeouts, records, and u
> This page assumes you understand the basics of MCP. See [MCP (Model Context Protocol)](/tech/en/mcp/mcp-model-context-protocol.md).
## 1. Why Choose a Remote MCP Service?
MCP servers generally run in one of two ways: the client starts them locally (stdio), or they are deployed as network services that clients connect to over HTTP. The latter is called Remote MCP. Hosted services such as Composio and Zapier deploy servers for you and manage authorization for SaaS applications. You only need a server URL to get started.
| Consideration | Self-Hosted MCP Server | Hosted Remote MCP Service |
| ----------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------- |
| **Deployment and operations** | You deploy, monitor, and update it | The service provider handles them |
| **Third-party authorization** | You implement OAuth or manage keys | Usually managed by the provider; the server URL or headers represent your authorization |
| **Available tools** | Developed for your system's needs | Determined by the applications and actions the provider supports |
| **Data flow** | Data passes only through your server | Tool arguments and results pass through the provider |
Common use cases:
* **Office automation**: Read or send Gmail messages, manage Google Calendar events, search Google Drive documents, and update Google Sheets.
* **Customer service and tickets**: Look up customer data and create or update tickets in systems such as Zendesk and Salesforce.
* **Project and development collaboration**: Create issues and update task statuses in Jira, Asana, Linear, and GitHub.
***
## 2. How MaiAgent Connects to Remote MCP
MaiAgent is an **MCP Client**: the Agent only decides which tool to call and which arguments to use; the platform makes the actual connection. Hosted services and your self-hosted servers use the same connection mechanism.
```mermaid
sequenceDiagram
participant A as Agent (LLM)
participant P as MaiAgent Platform (MCP Client)
participant S as Remote MCP Server
participant X as External Service (Gmail, Jira…)
P->>S: initialize → tools/list (with configured headers or OAuth token)
S-->>P: Tool list
P->>P: Filter by "Allowed tools" before passing to the model
A->>P: Tool call (name + JSON arguments)
P->>S: New session: initialize → tools/call
S->>X: Call external service API
X-->>S: Response
S-->>P: Tool result
P->>P: Convert to text, truncate oversized content, write tool execution record
P-->>A: Tool result
```
| Item | MaiAgent Behavior |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Transport** | Supports Streamable HTTP and SSE, determined by the URL: SSE is used when the path ends with `/sse`, contains `/sse/`, or the query string includes `transport=sse`; otherwise Streamable HTTP is used. Neither stdio nor WebSocket is supported. |
| **URL** | Must be an `https://` address accessible from the internet. Internal network addresses cannot be saved. Contact MaiAgent if you need them for an on-premises deployment. |
| **Authentication** | Three options: authorization embedded in the URL (as with server URLs from Composio and Zapier); a fixed API Key in "Headers (JSON)"; or an OAuth connector, through which the platform handles authorization and automatically refreshes tokens. If each user needs to use their own token, you can also configure contact MCP credentials. |
| **When the tool list is retrieved** | Whenever the Agent's tools are assembled, the platform calls `tools/list` on the server. Actions removed on the server are therefore no longer provided to the model on the next reply. |
| **Tool scope** | Each MCP tool (one server URL) has its own "Allowed tools (JSON array)" list. Once bound to this MCP tool, an Agent can only call tools on that list. New actions on the server **are not enabled automatically**. Return to the tool settings, click "Fetch again", and enable them. |
| **Timeouts and retries** | The MCP session read timeout is 30 seconds. For temporary errors such as connection interruptions, only read tools (safe to resend) are retried automatically, up to 3 times. |
| **Records and billing** | Each call is written to a tool execution record (tool, actual MCP tool name called, input arguments, output or error, and duration). Successful calls deduct Credits according to whether the tool reads or writes. Calls are not sent if Credits are insufficient. |
For the complete specifications on connections, authentication, retries, and error handling, see [Self-Hosted MCP Server Integration Specifications](/tech/en/mcp/self-hosted-mcp-server.md).
### Two Entry Points
* **Agent MCP tools**: Create an MCP tool in the admin interface, enter the server URL and authentication method, and bind it to an Agent. This is suitable for customer-facing support Agents or Agents for specific purposes.
* **MaiGPT connectors**: After an administrator enables a connector, members authorize it themselves and toggle its use in MaiGPT conversations.
***
## 3. Limitations and Notes
* **The server URL is a credential**: Server URLs generated by services such as Composio and Zapier contain authorization. Anyone who obtains the URL can call tools using your account. Enter it only in MaiAgent's tool settings; do not put it in role instructions, conversations, or public documentation. If leaked, regenerate it with the provider.
* **All users share the same account**: When using URL or fixed-header authentication, all users who chat through this Agent perform operations using the account originally authorized with the provider. For services tied to personal accounts (personal mailboxes or calendars), use OAuth connectors with individual contact authorization, or use only internal Agents.
* **Create separate MCP tools when different Agents need different permissions**: The allowed tools list is configured on the MCP tool. Agents bound to the same MCP tool share the same list.
* **Data passes through third parties**: Hosted services generally handle tool arguments and results. Evaluate this according to your data classification and regulatory requirements.
* **Enable reads before writes**: Only enable actions the Agent needs. Write actions are not retried automatically, but the model may still call them repeatedly. Check the service's behavior for actions such as creating, sending, and deleting.
* **Local MCP servers need a remote version**: MCP servers started locally with commands such as `npx` or `node` cannot be used directly. Use the provider's remote version or deploy one yourself as an HTTP service.
***
## 4. See the User Manual for Instructions
* [Create an MCP Tool](https://docs.maiagent.ai/build/tools/mcp-setup): URL, headers, OAuth connectors, allowed tools
* [Configure Tools for an Agent](https://docs.maiagent.ai/build/tools/configure_tools)
* [Configure Contact MCP Credentials](https://docs.maiagent.ai/build/tools/setup-contacts-mcp-credentials)
* [MaiGPT Connectors](https://docs.maiagent.ai/work/maigpt/connectors), [Manage Connectors (Administrators)](https://docs.maiagent.ai/work/maigpt/connectors/connectors-admin)
* [Tool Execution Records](https://docs.maiagent.ai/build/agent-ops/tool-execution-records)
For provider setup steps, see [Composio Integration](/tech/en/mcp/composio.md) and [Zapier Integration](/tech/en/mcp/zapier.md).
***
### Reference Links
* [Model Context Protocol Specification: Transports](https://modelcontextprotocol.io/specification/latest/basic/transports)
* [Model Context Protocol Specification: Authorization](https://modelcontextprotocol.io/specification/latest/basic/authorization)
* [Model Context Protocol Specification 2024-11-05: HTTP with SSE Transport](https://modelcontextprotocol.io/specification/2024-11-05/basic/transports)
---
# 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/remote-mcp.md?ask=&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.