Skip to main content

​
Overview

The Model Context Protocol (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 typeWho authenticatesWhen to use
API KeyThe organization (a shared credential)The server accepts a static API key / Bearer token passed as a header.
OAuthEach user, individuallyThe 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:
ModeDescription
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. Aster registers a client on the fly. Not all providers support this.
The latest MCP authorization spec prefers Client ID Metadata Documents (CIMD) where supported. Aster does not require CIMD yet — it’s tracked as a follow-up as tooling support matures.

​
Transports

TransportBest ForHow It Works
Streamable HTTP (recommended)ProductionUses HTTP for requests and optional streaming responses. The primary transport in the current MCP spec.
SSE (legacy)Older serversServer-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

1

Add an MCP Server

Navigate to Control Hub > Integrations and scroll down to MCP Servers. Click Add Server (admins only).
2

Choose an authentication type

  • API Key — add authentication headers (e.g. Authorization: Bearer your-api-key).
  • OAuth — choose an OAuth client mode (see below).
3

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)
4

(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.
5

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.
6

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.

​
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.
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.

​
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 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:
ServerURLTransportAuth
Hugging Facehttps://hf.co/mcpHTTPNone
Cloudflare Docshttps://docs.mcp.cloudflare.com/sseSSENone
Check awesome-remote-mcp-servers on GitHub for a community-maintained list of public MCP servers.

​
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

  • 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
  • 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
  • The server may be running but has no tools registered
  • Some servers require authentication before exposing 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
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.