MCP Service

The MCP Servers catalog brings the tool servers available through Aion into one place. Open Resources > MCP Servers to find servers from your Projects, manage eligible global servers, inspect their tools, copy connection examples, and review usage. Project servers come from MCP capabilities configured on Ions in Composer. Global servers are Aion-managed capabilities that can be available across an organization.

Before you begin

You need:

an active Aion organization;
a visible Project with an MCP-capable Ion, or an eligible global MCP server;
the permissions required by the server you want to use.

Browse MCP servers

Choose Project or Global

The catalog separates servers by where they are available:

View	What it contains	What you can change here
Project	MCP servers configured through Ions in one or more Projects.	Browse, inspect, and connect.
Global	Aion-provided MCP servers available across the organization.	Enable or disable eligible servers.

Project MCP configuration remains read-only on this page. To change which tools are allowed or blocked, edit the Ion’s MCP capability configuration in Composer.

Find a Project MCP server

Open Resources > MCP Servers. The Project tab opens by default.
Choose a Project, or select Show all projects.
Optionally choose an Environment, or select Show all environments.
Use Search MCP… to filter the visible servers.
Select View MCP server to open a server’s details.

The Project tab starts empty until you select a Project or Show all projects. Each result identifies its Project, environment, categories, required permissions, and current availability. A server may be Available, Review Required, or Unavailable. Use Environment to narrow the Project results to Projects with that environment name.

MCP Servers Project catalog with search, filters, enabled servers, visibility, and an Identity selector

Preview permissions for an Identity

Select a Personal, Principal, or Daemon Identity in the Permissions card to preview whether its assigned roles include the permissions listed by each server. This preview does not grant access or execute a request. It highlights missing permissions and moves closer matches higher in the results. See Aion Meta Tools for programmatic discovery and environment filtering, and Roles & Permissions for the permissions behind this preview.

Enable a global MCP server

Open the Global tab.
Find the MCP server you want to use.
Turn on Enabled.
Wait for confirmation that the server is enabled.

Some global servers are always enabled and show a locked switch. Servers that are not eligible for the current organization cannot be enabled. Project and Environment filters do not affect the Global list.

Authentication

Choose credentials based on where the MCP client runs:

Caller	Credential	How it is provided
Codex or Claude Code	OAuth or personal API key	Sign in interactively, or configure `AION_API_KEY`.
Script or non-OAuth client	Personal API key	Send the key as an `Authorization: Bearer` credential.
Remote Deployment	`AION_CLIENT_ID` and `AION_CLIENT_SECRET`	Copy the values Aion displays once.
Aion GitHub	`AION_CLIENT_ID` and `AION_CLIENT_SECRET`	Aion injects the values into the runtime.

OAuth for interactive clients

Use OAuth with interactive MCP clients such as Codex and Claude Code. Each Aion MCP endpoint publishes the authorization information the client needs. After you add the server, the client opens Aion sign-in and uses the resulting authorization when it connects. OAuth acts as the signed-in user. The servers and tools available to the client are limited by that user’s organization membership, visibility, and permissions.

Personal API keys

Use a personal API key when a user-operated client cannot complete OAuth or when you need non-interactive access. Create and revoke keys from Settings > Personal > API Keys, then export the key without putting its value in a client configuration:

export AION_API_KEY="YOUR_PERSONAL_API_KEY"

Copy the exact MCP URL from the selected server’s Usage tab. For Codex, configure the environment variable as the bearer-token source:

# ~/.codex/config.toml
[mcp_servers.my-aion-server]
url = "PASTE_MCP_URL_HERE"
bearer_token_env_var = "AION_API_KEY"

For Claude Code, add the server to .mcp.json and expand the environment variable in the request header:

{
  "mcpServers": {
    "my-aion-server": {
      "type": "http",
      "url": "PASTE_MCP_URL_HERE",
      "headers": {
        "Authorization": "Bearer ${AION_API_KEY}"
      }
    }
  }
}

Personal keys act as their users. They remain scoped to the organization selected when created and require the user’s current membership, server visibility, and MCP execution permissions. Revoke an exposed or unused key from the API Keys page. New requests stop authenticating after the revocation has propagated.

Deployment client credentials

Aion deployments use AION_CLIENT_ID and AION_CLIENT_SECRET:

Remote Deployment: Aion displays both values after you create the deployment. Copy them immediately and add them to the runtime’s environment. The client secret is shown only once and cannot be retrieved later.
Aion GitHub: Aion injects both values into the hosted runtime environment automatically.

The Aion SDK reads these variables, exchanges them for a short-lived Aion token, and refreshes the token as needed. SDK MCP adapters use that token automatically; do not send the raw client ID or secret to an MCP endpoint.

Permissions and attribution

OAuth and personal API-key connections are authorized as their users. A deployment connection authenticates with its Version bearer. Aion verifies forwarded usage attribution and authorizes its executor, or resolves the deployment’s current daemon for direct and autonomous calls. The retired Aion-Principal-Selector header is not accepted. Use the selected server’s Required Permissions list as the source of truth. MetaTools uses the same authentication paths and applies the caller’s visibility and permissions when it searches for or executes tools. Execution permission and usage attribution are separate. A distribution request retains its receiving agent and originator while downstream daemons execute its tools. Direct deployment work uses the deployment daemon and payer. See Identities and Runtime callbacks for these roles and headers.

Usage

Open Resources > MCP Servers, select a server, and open Usage. The page generates the exact endpoint and capability reference for the selected server.

Choose an access pattern

Pattern	Use it when
Direct server	Your client should load and call one server’s tools directly.
MetaTools	Your application should search and execute across visible servers without loading every tool definition.

Direct server examples target the selected server. MetaTools examples target Aion’s global MetaTools server and use aion_tool_search and aion_tool_execute to find and call eligible tools.

Choose a client

Client	Use it for	Authentication
Codex	Adding one remote MCP server to Codex.	OAuth or personal API key
Claude Code	Adding one streamable HTTP server to Claude Code.	OAuth or personal API key
Python SDK	Connecting an application to one capability reference.	Deployment client credentials
LangGraph	Loading MCP tools into a LangGraph application.	Deployment client credentials
Google ADK	Attaching an MCP toolset to a Google ADK agent.	Deployment client credentials

Connect an OAuth client

Copy the generated MCP URL into your client configuration. For Codex, the generated example follows this shape:

# ~/.codex/config.toml
[mcp_servers.my-aion-server]
url = "PASTE_MCP_URL_HERE"
auth = "oauth"

# Then authenticate once:
# codex mcp login my-aion-server

Complete Aion sign-in when the client prompts you. The connection succeeds when the client can list the server’s tools. If the server connects but a tool is unavailable, review the server’s required permissions and tool policy. For Claude Code, copy the generated command:

claude mcp add --transport http my-aion-server "PASTE_MCP_URL_HERE"

Use /mcp inside Claude Code to complete authentication.

Connect an Aion deployment

Choose SDK, SDK / LangGraph, or SDK / Google ADK, then copy the generated example. It includes:

the exact capability reference for the selected server;
an authenticated MCP endpoint;
the runtime context used to forward signed usage attribution or report a direct caller.

The example uses the deployment credentials described above. Keep its generated capability reference intact because the required subject and capability key depend on how the server is attached to the Project.

Inspect tools

Open a server to review its summary and tools:

Area	What it shows
Summary	Owner, capability key, MCP path, Project, environment, protocols, and required permissions.
Tools	Discovered tools, categories, policy status, review state, and discovery health.

The Tools tab groups tools as read-only, mutating, destructive, or unannotated. Its policy controls are informational; edit tool policy from the corresponding Ion in Composer. This example shows an Airtable server whose unannotated tools resolve to Block under the system default:

MCP server Tools tab showing Airtable tools blocked by the system-default policy

Monitor usage and cost

Open a server and select Metrics to inspect Credits Used, Principal Attribution, and usage categories. Use the reporting-period control to change the time range.

Troubleshoot a connection

Symptom	What to check
The client never opens Aion sign-in.	Confirm that the client is configured for OAuth and uses the generated URL.
The client rejects its credentials.	Sign in, confirm `AION_API_KEY` is exported, or verify deployment credentials.
No Project servers appear.	Select a Project or Show all projects, then check the Environment filter.
A server needs review or is unavailable.	Inspect its missing permissions, availability details, and environment.
A tool is unavailable after connecting.	Review its policy in Composer and the caller’s required permissions.

Aion Meta Tools

Use aion_tool_search to find tools within an authorized scope, then aion_tool_execute to call a selected result. Search returns the references needed for execution; it does not grant permission to invoke the tool. The target’s execution permissions, availability, and tool policy are checked when the call runs.

Resource discovery and environment boundaries

Choose a Project or organization scope that matches the task. Project-scoped access limits discovery to the permitted Project and configured Ions. The Project Agent role does not make every Project in the organization visible. Cross-project discovery requires broader CapabilityList authority, such as an organization-level grant, or explicit grants for the relevant Projects. User-operated discovery also respects the user’s visible Projects. For organization-scope searches by an Agent Identity, Aion normally derives an environment name from its bound Project. It selects authorized Projects with that same name, ignoring case. For example, a runtime bound to Production can find eligible resources in another Production Project only when its permissions include that Project. Matching names alone do not establish access. An explicit environmentName overrides the derived filter. It can select Development when that is intended, but cannot expand the caller’s permissions. If no unique environment can be derived, supply the intended environment explicitly rather than assuming organization access will search every environment. Eligible global MCP servers are separate from Project resources. They are not selected by Project environment names. Their discovery still requires the applicable capability-list authority and organization enablement; execution has its own permission checks. There is no all-organizations search scope.

What to do next

Follow the LangGraph MCP guide to load MCP tools in a LangGraph application.
Follow the Google ADK MCP guide to use MCP tools with an ADK agent.
Review Aion MCP for lower-level client integration.
Read Identities and Roles & Permissions for access and visibility rules.

Guides

Core Concepts

Ions

Resources

Distributions

Tools

Other

Before you begin

Browse MCP servers

Choose Project or Global

Find a Project MCP server

Preview permissions for an Identity

Enable a global MCP server

Authentication

OAuth for interactive clients

Personal API keys

Deployment client credentials

Permissions and attribution

Usage

Choose an access pattern

Choose a client

Connect an OAuth client

Connect an Aion deployment

Inspect tools

Monitor usage and cost

Troubleshoot a connection

Aion Meta Tools

Resource discovery and environment boundaries

What to do next

​Before you begin

​Browse MCP servers

​Choose Project or Global

​Find a Project MCP server

​Preview permissions for an Identity

​Enable a global MCP server

​Authentication

​OAuth for interactive clients

​Personal API keys

​Deployment client credentials

​Permissions and attribution

​Usage

​Choose an access pattern

​Choose a client

​Connect an OAuth client

​Connect an Aion deployment

​Inspect tools

​Monitor usage and cost

​Troubleshoot a connection

​Aion Meta Tools

​Resource discovery and environment boundaries

​What to do next

Before you begin

Browse MCP servers

Choose Project or Global

Find a Project MCP server

Preview permissions for an Identity

Enable a global MCP server

Authentication

OAuth for interactive clients

Personal API keys

Deployment client credentials

Permissions and attribution

Usage

Choose an access pattern

Choose a client

Connect an OAuth client

Connect an Aion deployment

Inspect tools

Monitor usage and cost

Troubleshoot a connection

Aion Meta Tools

Resource discovery and environment boundaries

What to do next