# Connect a custom MCP server

> Add any MCP server to FlyMyAI - aggregator (Composio, Smithery, Pipedream, Zapier), self-hosted, or a provider's own OAuth MCP such as Notion, Linear or Slack - through the "Add custom MCP" dialog.

The built-in MCPs in FlyMyAI cover the most common services. When you
need something we don't ship out of the box - a niche SaaS, an
internal HTTP service, or a server you generated through a third-party
aggregator like Composio, Smithery, Pipedream or Zapier - point FlyMyAI
at the server's URL and we connect to it directly.

This page explains every field of the **Add custom MCP** dialog so you
know what to paste where. For per-provider walkthroughs (Composio,
Smithery, Pipedream, Zapier MCP) jump to
[Provider recipes](https://docs.flymy.ai/mcp/custom/provider-recipes.md).

## When to use a custom server

Pick a custom server when **at least one** of these is true:

- The service has a hosted MCP endpoint (most aggregators do).
- You self-host an MCP server and can expose it over HTTPS.
- You want a tool we haven't shipped a built-in for yet.

If we already ship a built-in for the integration (Slack, Notion,
Gmail, GitHub, ...), use the built-in - it's faster, the auth is
handled, and tool descriptions are tuned for our agents. Use a custom
server when you want the provider's own MCP endpoint instead (for
example Slack's official MCP): it signs in with [OAuth](#oauth).

## Open the dialog

1. Sign in to [app.flymy.ai](https://app.flymy.ai).
2. Open **MCP configs** from the left sidebar (or the agent setup
   sidebar inside any chat).
3. Click **+ Connect MCP tool**. The catalog drawer opens.
4. At the top of the catalog click **Add custom MCP**.

The **Add custom MCP** dialog appears with two sections: basic fields
(Name, URL, Type) and an **Advanced settings** drawer for auth.

## Fields

### Name

Free-form label that shows up in your tool list and in agent settings.
Use whatever makes sense to you - `Composio · Linear`, `Internal
billing-mcp`, `Zapier ops`. Required.

### URL

The full HTTPS URL of the MCP endpoint. **Must start with `https://`**
(or `http://` for localhost during development).

Common shapes:

| Shape | Used by | Example |
| --- | --- | --- |
| `…/mcp` | Composio, Klavis, most Streamable-HTTP servers | `https://mcp.composio.dev/composio/server/<uuid>/mcp` |
| `…/sse` | Smithery, Pipedream, classic SSE servers | `https://server.smithery.ai/<slug>/mcp/sse?api_key=…` |
| `…?api_key=…` | Servers that take auth in the query string | `https://mcp.zapier.com/api/mcp/s/<token>/mcp` |

Whatever shape your provider gives you, paste the full URL **including
any query string they include**.

### Type

Selects the MCP transport. Pick whichever your provider documents.

- **Streamable HTTP** *(default)* - the modern transport. Use for
  Composio, Klavis, most 2025-era servers.
- **SSE (Server-Sent Events)** - the older transport. Use for
  Smithery, Pipedream, and any provider whose URL ends in `/sse`.

Picking the wrong type is the #1 reason a connection fails - if you
get "transport mismatch" errors, flip this and reconnect.

## Advanced settings

Click **Advanced settings** to reveal authentication fields. Leave
everything default if your URL already carries the credential in the
query string (Zapier MCP, some Composio servers).

### Authentication Type

| Option | When to use |
| --- | --- |
| **None** | URL already contains the token, or the server is genuinely public. |
| **API Key** | Provider gives you an `x-api-key` (or similar) header value. |
| **Bearer Token** | Provider gives you an `Authorization: Bearer …` token. Most OAuth-style aggregators. |
| **Basic Auth** | Provider gives you a username + password pair. Rare; mostly self-hosted. |
| **OAuth** | The server signs you in with the provider (the MCP authorization standard): Notion, Linear, Slack's own MCP and other hosted MCP servers. See [OAuth](#oauth). |

### Credential fields

Shown conditionally based on the auth type:

| Auth type | Field(s) | Where the value comes from |
| --- | --- | --- |
| API Key | `API Key` | Provider dashboard → API keys / personal token. |
| Bearer Token | `Bearer Token` | Provider dashboard → access token, or OAuth callback. |
| Basic Auth | `Username`, `Password` | Self-hosted server's auth config. |

Credentials are stored encrypted in the FlyMyAI backend and only
re-injected at request time - they're never echoed back into the UI.

## OAuth

Pick **OAuth** when the server asks you to sign in with the provider.
The URL must start with `https://`.

1. Fill in Name and URL, set **Authentication Type** to **OAuth** and
   click **Save and sign in**.
2. FlyMyAI finds the server's sign-in and opens the provider's consent
   page in a pop-up.
3. Approve. The pop-up closes, the server connects and its tools appear.

The grant is stored encrypted and refreshed automatically. When the
provider revokes it, the server shows **Reconnect needed**: open it and
click **Reconnect**. **Disconnect** forgets the grant.

### Servers that register FlyMyAI automatically

Many hosted MCP servers let FlyMyAI register itself, so there is
nothing else to enter:

| Service | URL |
| --- | --- |
| Notion | `https://mcp.notion.com/mcp` |
| Linear | `https://mcp.linear.app/mcp` |

### Your own OAuth app

Some providers have no automatic registration. FlyMyAI then says
*"This server has no automatic registration - create an OAuth app there
and paste its client id/secret"* and shows the redirect URL:

```
https://backend.flymy.ai/api/v1/agents/mcp-servers/oauth/callback/
```

1. Create an OAuth app with the provider and add that redirect URL to it.
2. In the dialog open **Advanced: your own OAuth app** and paste the app's
   **Client ID** and **Client secret**. **Scopes** is optional: leave it
   blank to request the scopes the server asks for.
3. Click **Save and sign in** again.

The client secret is write-only: FlyMyAI never shows it again, and a
blank field keeps the saved one.

### Slack's official MCP

Slack's MCP (`https://mcp.slack.com/mcp`) searches messages and files,
reads channels, threads and DMs, sends messages, works with canvases and
lists, all as you. Slack does not register apps automatically, and it lets
only apps from the Slack Marketplace or internal apps of your own
workspace use its MCP, so you create an internal Slack app once:

1. Open [api.slack.com/apps](https://api.slack.com/apps), click **Create
   New App** → **From scratch** and pick your workspace. Keep the app
   internal to that workspace: do not distribute it.
2. Under **Agents & AI Apps**, turn on **Model Context Protocol**.
3. Under **OAuth & Permissions** → **Redirect URLs**, add
   `https://backend.flymy.ai/api/v1/agents/mcp-servers/oauth/callback/`
   and click **Save URLs**.
4. Under **OAuth & Permissions** → **User Token Scopes**, add the scopes
   Slack's MCP tools use (from [Slack's MCP server
   reference](https://docs.slack.dev/ai/mcp-server/)):
   `search:read.public`, `search:read.private`, `search:read.mpim`,
   `search:read.im`, `search:read.files`, `search:read.users`,
   `channels:history`, `groups:history`, `mpim:history`, `im:history`,
   `channels:read`, `groups:read`, `mpim:read`, `channels:write`,
   `groups:write`, `im:write`, `mpim:write`, `chat:write`, `files:read`,
   `files:write`, `reactions:read`, `reactions:write`, `canvases:read`,
   `canvases:write`, `lists:read`, `lists:write`, `users:read`,
   `users:read.email`, `emoji:read`. Leave out what you don't want the
   agent to do.
5. Under **Basic Information** → **App Credentials**, copy the **Client
   ID** and **Client Secret**.
6. In FlyMyAI open **Add custom MCP**: Name `Slack`, URL
   `https://mcp.slack.com/mcp`, Type **Streamable HTTP**, Authentication
   Type **OAuth**, then **Advanced: your own OAuth app** with the Client ID
   and Client Secret. Click **Save and sign in** and approve in Slack.

If your workspace requires app approval, a Slack admin approves the app
first.

### From an assistant or from code

- **Agents MCP** (Claude, ChatGPT and other assistants signed in to
  FlyMyAI): `add_mcp_server` with `auth_type: "oauth"`, then
  `authorize_mcp_server` returns a link that you open to approve. The
  assistant never asks you to paste a client secret into the chat: it
  sends you to the app to enter it.
- **REST**: `POST /api/v1/agents/mcp-servers/` with `auth_type: "oauth"`
  (and optionally `oauth_client_id`, `oauth_client_secret`,
  `oauth_scopes`), then `POST /api/v1/agents/mcp-servers/<id>/authorize/`
  returns `authorize_url`, `redirect_uri` and `expires_at`. The link works
  once, for 15 minutes. An answer with `code: "oauth_client_required"`
  carries the `redirect_uri` to register in your own OAuth app.
- **Python SDK** (`pip install 'flymyai==1.2.0rc9'`): `client.mcp_servers.create(...)`,
  `client.mcp_servers.authorize(server_id)`; `McpServerOAuthError` carries
  the `code` and `redirect_uri`.

## Save and connect

Click **Save**. FlyMyAI does two things:

1. Creates the server record (`POST /agents/mcp-servers/`).
2. Opens a connection and discovers the available tools (`POST
   /agents/mcp-servers/<id>/connect/`). An OAuth server connects after
   you approve the sign-in instead.

If the connect step succeeds, the tool list expands into the
configuration panel - those are the verbs your agent can now call.
Toggle individual tools on/off if you want to expose only a subset.

## Use it from an agent

Open any agent → **Tools** tab → enable your new MCP. The agent will
see the tool descriptions and call them when relevant. No code change
needed.

## Edit or remove

- **Edit** - hover the tool tile in `MCP configs` and click the
  pencil. Same dialog opens; updates re-trigger a connect.
- **Remove** - click the trash icon. Agents that referenced the tool
  will skip it on the next run.

## Troubleshooting

- **`Failed to connect`** - the URL is unreachable from our side. Open
  it in a browser/curl with the same auth header to confirm it's
  online.
- **`Transport mismatch`** - flip **Type** between Streamable HTTP and
  SSE.
- **`401 Unauthorized` / `403 Forbidden`** - the credential is wrong,
  expired, or missing the right scope. Regenerate it in the provider
  dashboard and paste again.
- **Tools list is empty** - the server connected but exposes zero
  tools. Check the provider's tool configuration - many aggregators
  let you toggle which tools are enabled per-server.
- **Server works once, then fails** - tokens with short TTLs (some
  Bearer tokens) need rotation. Use **OAuth** instead when the server
  supports it: FlyMyAI refreshes the token itself.
- **Sign-in needed** / **Reconnect needed** - open the server and click
  **Connect** or **Reconnect**.
- **"This server has no automatic registration"** - create an OAuth app
  with the provider and paste its client ID and secret, see
  [Your own OAuth app](#your-own-oauth-app).
- **Nothing happens on Save and sign in** - the browser blocked the
  pop-up. Allow pop-ups for app.flymy.ai and click **Connect** on the
  server.

## Next

- [Provider recipes](https://docs.flymy.ai/mcp/custom/provider-recipes.md) - exact steps for
  Composio, Smithery, Pipedream and Zapier MCP.
- [MCP overview](https://docs.flymy.ai/mcp.md) - browse the built-in catalog.
