> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asteragents.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Servers

> Connect remote MCP servers to extend your agents with external tools

## Overview

The [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) is an open standard that lets AI agents interact with external tools and services through a unified interface. Aster Agents supports connecting to any remote MCP server, giving your agents access to thousands of third-party tools without custom integration work.

When an agent has MCP servers assigned, it automatically discovers and can call all tools provided by those servers during conversations.

## Authentication types

Aster supports two ways to authenticate against a remote MCP server:

| Auth type   | Who authenticates                      | When to use                                                                                                |
| ----------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **API Key** | The organization (a shared credential) | The server accepts a static API key / Bearer token passed as a header.                                     |
| **OAuth**   | Each user, individually                | The server requires per-user sign-in. Each user connects their own account and tools run with their token. |

### OAuth client modes

OAuth servers come in two flavors depending on how the OAuth client is provisioned:

| Mode                                                         | Description                                                                                                                                                                                      |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Pre-created OAuth app** (`known_credentials`, recommended) | An admin creates an OAuth/MCP auth app on the provider's side, whitelists Aster's callback URL, and pastes the generated client ID and secret into Aster. Required by providers such as HubSpot. |
| **Dynamic Client Registration** (`dynamic`)                  | A compatibility mode for servers that support [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591). Aster registers a client on the fly. Not all providers support this. |

<Note>
  Aster also supports **Client ID Metadata Documents (CIMD)** — the latest MCP authorization spec's preferred registration model. When a server's authorization endpoint advertises `client_id_metadata_document_supported` (e.g. Tableau's hosted MCP), Aster presents a URL-based client ID pointing at its hosted metadata document instead of registering a client dynamically. This happens automatically in `dynamic` mode; no extra configuration is needed.
</Note>

## Transports

| Transport                         | Best For      | How It Works                                                                                            |
| --------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------- |
| **Streamable HTTP** (recommended) | Production    | Uses HTTP for requests and optional streaming responses. The primary transport in the current MCP spec. |
| **SSE** (legacy)                  | Older servers | Server-Sent Events. Kept for backward compatibility with older MCP server implementations.              |

If the server documentation doesn't specify, try Streamable HTTP first.

## Prerequisites

* An MCP server URL (hosted by a third party or self-hosted)
* For **API Key** servers: any required credential (API key, Bearer token, etc.)
* For **OAuth** servers in pre-created mode: the ability to create an OAuth app on the provider and whitelist a callback URL
* Admin access to your Aster Agents organization (to add/edit/delete servers)

## Setup Guide

<Steps>
  <Step title="Add an MCP Server">
    Navigate to **Control Hub > Integrations** and click **Add integration**. At the top of the
    library, click **Add a custom MCP server** (admins only) to open the server dialog.

    If the server you want is already listed in the library, add it directly from its card instead —
    the dialog opens pre-filled.
  </Step>

  <Step title="Choose an authentication type">
    * **API Key** — add authentication headers (e.g. `Authorization: Bearer your-api-key`).
    * **OAuth** — choose an OAuth client mode (see below).
  </Step>

  <Step title="Configure the server">
    Fill in the server details:

    * **Name**: A display name (e.g. "HubSpot", "Cloudflare Docs")
    * **Transport**: Streamable HTTP (recommended) or SSE
    * **URL**: The server's MCP endpoint URL
    * **Auth fields**: headers (API Key) or OAuth client mode + credentials (OAuth)
  </Step>

  <Step title="(OAuth, pre-created mode) Whitelist the callback URL">
    The dialog displays Aster's OAuth callback URL — for example
    `https://www.asteragents.com/api/mcp/oauth/callback`. Add this **exact** URL as an allowed
    redirect URI in the provider's OAuth app, then paste the provider's client ID and secret into Aster.
  </Step>

  <Step title="Connect or test">
    * **API Key** servers: click the **play** button to test connectivity. A successful test reports how many tools were discovered.
    * **OAuth** servers: click **Connect** to start the OAuth flow. After you consent on the provider's site, you'll return to Aster with the server marked **Connected**.
  </Step>

  <Step title="Assign to an Agent">
    Go to **Control Hub > Agents**, edit an agent, and scroll to the **MCP Servers** section. Check the servers you want this agent to use. For OAuth servers, each user who chats with the agent must connect their own account first.
  </Step>
</Steps>

## The OAuth connection flow (for users)

1. An admin adds an OAuth MCP server in **Integrations**.
2. Each user clicks **Connect** on that server card.
3. Aster redirects them to the provider's consent screen.
4. After they approve, the provider redirects back to Aster's callback, which stores a per-user session.
5. The server now shows **Connected** for that user. Their agents can call its tools with their own token.
6. Users can **Disconnect** at any time, which deletes their stored session.

<Note>
  OAuth connections are **per user**. Two users connecting to the same server each get their own
  independent session and token. Scheduled tasks run with the connection of the user who created the task.
</Note>

### Staying connected

Access tokens are refreshed automatically in the background, so a connection stays alive indefinitely on a healthy server — including providers that rotate refresh tokens on every use.

If a connection can no longer be refreshed (the provider revoked it, or the grant expired), Aster flags it rather than failing silently:

* The server card in **Control Hub > Integrations** shows **Connection error** with a **Connect** button to reauthorize.
* In chat, a banner appears above the composer: *"Your {server} connection needs to be reconnected before this agent can use its tools."*

Clicking **Connect** runs the OAuth flow again; the agent regains the server's tools on the next message. Transient provider outages do **not** flag the connection — those retry automatically.

## Example: Public MCP Servers

Many services offer hosted MCP servers you can connect directly:

| Server          | URL                                   | Transport | Auth |
| --------------- | ------------------------------------- | --------- | ---- |
| Hugging Face    | `https://hf.co/mcp`                   | HTTP      | None |
| Cloudflare Docs | `https://docs.mcp.cloudflare.com/sse` | SSE       | None |

<Tip>
  Check [awesome-remote-mcp-servers](https://github.com/jaw9c/awesome-remote-mcp-servers) on GitHub for a community-maintained list of public MCP servers.
</Tip>

## How It Works at Runtime

When a user sends a message to an agent with MCP servers:

1. **Resolve** — Aster loads the agent's assigned servers and, for OAuth servers, the calling user's connection.
2. **Connect** — Aster opens a connection to each enabled server (API key servers use stored headers; OAuth servers use the user's token).
3. **Discover** — Tools are fetched from each server via the MCP protocol.
4. **Namespace** — MCP tool names are prefixed per server (e.g. `hubspot_12__create_contact`) so they never collide with built-in tools or with another server's tools.
5. **Execute** — The model can call any discovered tool during the conversation.
6. **Cleanup** — Connections are closed after the response completes.

If a user hasn't connected an OAuth server (or their connection is in an error state), that server is skipped for them (logged, no crash) — other tools still work, and chat shows a banner prompting them to connect.

## Security

* **Secrets redacted** — Auth headers and OAuth client secrets are redacted (`[REDACTED]`) in API responses. Editing a server preserves the stored secret unless you replace it.
* **URL validation** — Server URLs are validated before saving and before any test/connect. In production, `https` is required and localhost / private / link-local / cloud-metadata addresses are blocked.
* **Organization-scoped** — Only admins can add, edit, or delete MCP servers. All users can connect their own OAuth accounts.
* **Per-agent assignment** — Each agent only accesses the servers explicitly assigned to it.
* **Inline-config testing is admin-only** — Testing an unsaved server config (arbitrary URL/headers) is restricted to admins.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection Failed (API Key)">
    * Verify the URL is correct and the server is running
    * Check that you selected the right transport type (HTTP vs SSE)
    * Ensure any required auth headers are included
  </Accordion>

  <Accordion title="OAuth Connect fails or loops">
    * Confirm the callback URL is whitelisted **exactly** in the provider's OAuth app
    * Verify the client ID and secret are correct (re-enter the secret if unsure)
    * Check the requested scopes are permitted for the OAuth app
  </Accordion>

  <Accordion title="No Tools Discovered">
    * The server may be running but has no tools registered
    * Some servers require authentication before exposing tools
  </Accordion>

  <Accordion title="Agent Not Using MCP Tools">
    * Confirm the MCP server is assigned to the agent in Control Hub
    * Ensure the server is enabled
    * For OAuth servers, confirm the current user has connected their account
    * Check the server card in Integrations for a **Connection error** badge — if present, click **Connect** to reauthorize
    * Try prompting the agent to use a specific tool by name
  </Accordion>

  <Accordion title="Connection error / 'needs to be reconnected' banner">
    The provider rejected the stored credentials — typically because the grant was revoked on the
    provider's side or expired. Click **Connect** on the server card in
    **Control Hub > Integrations** to run the OAuth flow again. Your agents regain the server's
    tools immediately; no agent configuration changes are needed.
  </Accordion>
</AccordionGroup>