Project MCP

The Project MCP server gives MCP clients a semantic, permission-checked way to inspect and change Aion Projects. It works with the Ions in a Project graph. Every change is a two-step operation. A mutation tool first returns a preview. The caller reviews that preview and then calls project_config_confirm_mutation to apply it. The server does not expose raw collaborative-document mutations.

The Project MCP server and the Project Configuration Agent are separate surfaces. Direct MCP clients call the tools described here. The hosted agent interprets natural-language requests and selects the same tools on behalf of its authenticated caller. Both paths enforce the caller’s current permissions.

Before you begin

You need:

an active Aion organization;
access to the Global catalog under Resources > MCP Servers;
permission to execute the Project MCP capability;
the resource permissions required by each Project operation;
the UUID of an existing Project for Project-scoped operations.

See MCP Servers for OAuth, personal API-key, deployment credential, and client configuration guidance.

Enable and connect

Open Resources > MCP Servers.
Select Global.
Find Aion Project Configuration and turn on Enabled.
Open the server and select Usage.
Choose Direct server, then copy the generated endpoint and configuration for your MCP client.
Connect the client and verify that tools/list includes project_config_inspect.

The server is organization-managed and authenticated. It does not use a fixed public endpoint.

How changes work

Use this workflow for Project creation, Project deletion, and graph changes:

Inspect the current Project.
Call a mutation tool to create a preview.
Review the preview’s summary, affected resources, required permissions, validation issues, target hash, and expiry.
Ask the user to approve the proposed change.
Call project_config_confirm_mutation with the preview’s operationId and confirm: true.
Check the returned operation status. Retry the same confirmation when the operation is still accepted or pending.

Unconfirmed previews expire after 30 minutes. Confirmation rechecks authorization and verifies that the Project still matches the previewed baseline. If the Project changed, inspect it again and create a new preview. Mutation tools accept optional request metadata:

Field	Purpose
`requestId`	Caller-owned idempotency key with a maximum length of 256 characters.
`reason`	Audit context explaining why the change was requested.

Reusing a requestId for the same normalized request returns the existing operation. Reusing it for different input returns request_id_conflict.

Inspect a Project

Call project_config_inspect before proposing a change:

{
  "projectId": "019fab58-f84c-79c5-8301-70ec6a9d30ed"
}

The response includes:

Project metadata without collaborative-document state;
ionsByType, with Ion labels, positions, safe attributes, and persisted entity references;
directed edges and ordered Sequence paths;
graph validation issues and environment names;
availableIonCreationActions, containing the actions available to the caller;
operations supported by the caller’s current Project permissions.

The inspection projection excludes capability authentication, secrets, attachment payloads, attachment runtime overlays, and arbitrary editor data.

Preview an Ion addition

First call project_config_list_ion_creation_actions with the Project UUID:

{
  "projectId": "019fab58-f84c-79c5-8301-70ec6a9d30ed"
}

Each returned descriptor identifies the action ID, produced ionType, parameter schema, additional authorization actions, and interaction hint. Use the returned schema rather than hard-coding the available actions; availability can depend on the caller and installed Aion modules. Then call project_config_add_ion with one returned action:

{
  "projectId": "019fab58-f84c-79c5-8301-70ec6a9d30ed",
  "actionId": "behavior.existing",
  "parameters": {
    "agentBehaviorId": "019fab5b-80de-70e5-a731-37d66947453c"
  },
  "ionId": "triage-agent",
  "position": {
    "x": 640,
    "y": 260
  },
  "metadata": {
    "requestId": "add-project-ion-2026-07-28",
    "reason": "Add the approved behavior"
  }
}

Supply every required value from the selected action’s parameters descriptor. The response is a preview, not a persisted change. Review these fields before confirmation:

Field	What to check
`operationId`	Stable UUID used to confirm or recover this operation.
`expiresAt`	Time by which confirmation must begin.
`summary`	Human-readable description of the proposed change.
`requiredAuthorizationPermissions`	Complete permission set resolved from the request.
`affectedProjects` and `affectedIons`	Resources the operation expects to change.
`plannedChange`	Normalized semantic operation that would be applied.
`validationIssues`	Planning or graph errors that prevent safe application.
`canApply`	Whether the preview is eligible for confirmation.
`targetConfigurationHash`	Canonical hash of the proposed Project configuration, when applicable.

Do not confirm a preview when canApply is false.

Confirm the preview

After the user approves the preview, call:

{
  "operationId": "019fab5a-8c85-7f5b-8093-7df1de5b1754",
  "confirm": true
}

Confirmation can report Accepted, Pending, Committed, or ExecutionFailed. A committed response can include the resulting Project checkpoint UUID. A terminal failure includes a stable code, a safe message, and whether the operation is retryable. Calling confirmation again with the same operation UUID recovers the durable outcome when the initial response was lost or execution was still pending. It does not create a second mutation.

Preview a batch

Use project_config_preview_change when later commands depend on Ions added earlier in the same change. Each command must define exactly one of addIon, connectIons, updateIonConfig, or setIonDaemonIdentity. This example adds an existing Behavior Ion and connects an existing Distribution Ion to it:

{
  "projectId": "019fab58-f84c-79c5-8301-70ec6a9d30ed",
  "commands": [
    {
      "commandId": "019fab5b-584a-72fb-bbe8-cc5d32564b12",
      "addIon": {
        "actionId": "behavior.existing",
        "parameters": {
          "agentBehaviorId": "019fab5b-80de-70e5-a731-37d66947453c"
        },
        "ionId": "triage-agent",
        "position": {
          "x": 640,
          "y": 260
        }
      }
    },
    {
      "connectIons": {
        "source": {
          "existingIonId": "incoming-distribution"
        },
        "target": {
          "addedByCommandId": "019fab5b-584a-72fb-bbe8-cc5d32564b12"
        }
      }
    }
  ],
  "metadata": {
    "requestId": "add-and-connect-triage-agent",
    "reason": "Route incoming work to the approved behavior"
  }
}

An Ion reference must define exactly one of:

existingIonId for an Ion already in the Project; or
addedByCommandId for an Ion produced by an earlier command in the batch.

Assign a UUID commandId when a later command needs to reference the added Ion. The entire ordered batch receives one preview and one confirmation.

Tool reference

All mutation tools in this table create previews. Only project_config_confirm_mutation can apply a preview.

Tool	Main input	Required resource permission
`project_config_inspect`	`projectId`	`project.read`
`project_config_list_ion_creation_actions`	`projectId`	`project.read`
`project_config_list_models`	No input	No additional resource permission
`project_config_list_daemon_identities`	`projectId`	`project.read`, `agent_identity.read`
`project_config_create_project`	Organization, name, optional fields	`project.create`
`project_config_create_daemon_identity`	Project and profile	`project.update`, `agent_identity.create`
`project_config_delete_project`	`projectId`, repeated `confirmedProjectId`, optional `metadata`	`project.delete`
`project_config_add_ion`	Project, action, parameters, placement	`project.update` plus action requirements
`project_config_connect_ions`	`projectId`, `sourceIonId`, `targetIonId`, optional edge ID	`project.update`
`project_config_update_ion_config`	`projectId`, `ionId`, `set`, `remove`, optional `metadata`	`project.update`
`project_config_set_ion_daemon_identity`	Project, Ion reference, optional identity UUID	`project.update`
`project_config_preview_change`	Project and ordered commands	`project.update` plus command requirements
`project_config_confirm_mutation`	`operationId`, `confirm`	Complete permission set recorded by the preview

The MCP capability also requires execution permission. Ion-creation actions can add more specific requirements, such as permission to read a selected behavior or create a Deployment. The server publishes static requirements in the tool’s aion.authorization annotation and resolves request-specific targets before preparation.

Project creation

project_config_create_project accepts:

required organizationId and projectName;
optional description and environmentName;
optional request metadata.

It allocates the Project identity during preview. The Project is not persisted until confirmation succeeds.

Project deletion

project_config_delete_project requires projectId and confirmedProjectId to contain the same Project UUID. This explicit acknowledgement creates a deletion preview; the preview still requires a separate confirmation call.

Ion configuration

project_config_update_ion_config applies a closed patch to supported non-auth configuration variables on Behavior and Distribution Ions:

set inserts or replaces key-value pairs;
remove deletes keys;
the same key cannot appear in both collections;
at least one key must be set or removed.

Capability authentication, secret fields, and identity selection are not supported through this tool.

Models

Call project_config_list_models with an empty object to list every text chat-completion model accepted by Aion LLM fields. Results are ordered by model ID and include the display name, a description capped at 512 characters, and available per-token prices in Aion credits:

{}

The pricing projection includes uncached input, cached-input read, cached-input write, and output token prices. Unavailable pricing fields are omitted. Listing models does not grant permission to invoke them; actual model calls remain permission-checked and billed at the model-service ingress.

Daemon identities

Use project_config_list_daemon_identities to discover organization-local daemon identities that are unassigned or already assigned within the target Project. It returns identity UUIDs and current Ion assignments. project_config_create_daemon_identity creates a preview for a new daemon identity:

{
  "projectId": "019fab58-f84c-79c5-8301-70ec6a9d30ed",
  "name": "Support workflow daemon",
  "atName": "support-workflow",
  "biography": "Executes the support agent behavior"
}

Confirm the returned operation before using its identity UUID. To assign a known identity to an existing Behavior or Distribution Ion, call:

{
  "projectId": "019fab58-f84c-79c5-8301-70ec6a9d30ed",
  "ion": {
    "existingIonId": "triage-agent"
  },
  "daemonIdentityId": "019fab60-bdfa-7a42-a823-a86909063187"
}

Omit daemonIdentityId to preview clearing the assignment. Project inspection reports only daemonConfigured; use the permission-checked identity-list tool when the caller needs the UUID.

Common errors

Code	Meaning	Next action
`authorization_denied`	A required permission is missing.	Review the caller’s role and reach.
`preview_not_applicable`	Validation issues prevent confirmation.	Correct the issues and request a new preview.
`preview_expired`	The cached preview and durable admission are unavailable.	Repeat the original preview request.
`preview_stale`	The Project changed after the semantic preview.	Inspect the Project and create a new preview.
`stale_project_baseline`	Project metadata changed after a lifecycle preview.	Recreate the lifecycle preview.
`request_id_conflict`	The request ID has different input.	Use the original input or a new ID.
`operation_busy`	Another request owns the operation lock.	Retry the same operation shortly.
`ion_creation_action_unavailable`	The action is unavailable.	List actions again for the same Project.
`invalid_ion_creation`	The selected action or its parameters are invalid.	Correct the action parameters.
`operation_unavailable`	The operation is absent or inaccessible.	Use the original caller and operation ID.

Errors use structured MCP output:

{
  "error": {
    "code": "preview_stale",
    "message": "Project changed after the configuration preview"
  }
}

Security and attribution

Direct OAuth and personal API-key calls are authorized as their authenticated user.
Deployment and agent calls are authorized as the resolved Identity selected by the trusted Aion runtime context.
Agent-mediated A2A calls require an authenticated caller and cannot fall back to the hosted daemon’s authority.
Cross-organization Project access is rejected even when the MCP server is globally visible.
Project checkpoints are attributed to the user or Identity whose permissions authorized the change.

What to do next

Use MCP Servers to configure a direct client or an Aion deployment.
Review Roles & Permissions for Project reach and Identity assignments.
Open Composer to inspect the resulting Project graph and checkpoint history.

Agent Instructions

Use this section as the operating contract for an agent that configures Aion Projects. Read the complete page before planning a mutation. MCP clients can load the same text through the resource URI https://docs.aion.to/tools/project-configuration-mcp.md.

Choose an integration path

Use one of these paths:

Direct Project MCP: connect your own agent to the organization-enabled global Project MCP server. Authenticate the MCP connection with the user or agent principal whose permissions should authorize each operation.
Project Configuration Agent over A2A: add the Project Configuration Agent Behavior Ion to a Project, connect it to an authenticated A2A Distribution Ion, and send natural-language requests to that A2A endpoint. The hosted agent has Project MCP tools and supplementary Aion Docs tools. It authorizes Project MCP calls as the authenticated A2A caller; its daemon identity is the executor, not fallback authority.

Do not ask either path to accept a principal ID in tool arguments. Aion derives caller authority from the authenticated transport and trusted runtime context.

Follow the Project mutation workflow

For every configuration request:

Call project_config_inspect and retain the current Project view.
Call project_config_list_ion_creation_actions instead of inventing Ion templates or action parameters.
Call project_config_list_models when an action requires an Aion model ID.
Use the daemon identity list, creation, and assignment tools only when the target Ion needs daemon authority.
Build one semantic preview. Use project_config_preview_change when commands depend on earlier commands or an identity move must be atomic.
Present the preview summary, affected resources, permission requirements, and validation issues to the user.
Call project_config_confirm_mutation only after explicit approval and only when canApply is true.
Retain the operationId. Retry confirmation with that same ID to recover an accepted or pending durable outcome.
Re-inspect after commitment before planning another dependent change.

Never construct an Ion by fully populating its document representation. Select an action from the server catalog and provide only the parameters declared by that action. The server allocates identities and returns the canonical template.

Build and deploy a LangGraph agent

Project MCP configures the Aion side of an agent deployment. A typical LangGraph workflow is:

Build and run the graph by following the LangGraph quickstart.
Create or select the GitHub repository outside Project MCP, then install and authenticate the Aion GitHub App.
Inspect the target Project and list available Ion-creation actions.
Select the catalog actions for the GitHub Deployment, Behavior, and A2A Distribution Ions. Supply the repository, entrypoint, behavior, and model identifiers requested by their descriptors.
Create or select a daemon identity when the Behavior or Distribution needs automated Project authority.
Preview the complete graph change, obtain explicit approval, and confirm it.
Complete any provider OAuth or external service-identity setup outside Project MCP.
Verify the resulting Project in Composer, then call the deployed agent through its A2A endpoint.

An external LangGraph agent can also load Project MCP directly. See Using MCP with LangGraph for authenticated MCP tool loading.

Respect configuration boundaries

Project MCP does not:

write or modify the caller’s LangGraph source;
create a GitHub repository;
install or authenticate the Aion GitHub App;
create external provider service identities;
complete provider OAuth or consent;
return stored secrets; or
grant permission to invoke a model merely because it listed that model.

Project MCP can create Aion daemon agent identities through its permission-checked preview and confirmation workflow.

Handle daemon uniqueness and concurrent changes

A daemon identity belongs to one organization and can be assigned to at most one active AgentEnvironment. Do not use an identity from a personal or different organization workspace. To move an identity between Ions, submit one batch that clears the current Ion and assigns the destination Ion in the same preview. The final state must contain one assignment. A batch that assigns one identity to multiple Ions is rejected without partial promotion. If validation reports an assignment conflict, re-inspect the Project and list daemon identities again. Do not infer success from a persistence error or retry with a new identity blindly.

Recover from stale or unavailable previews

For preview_stale or stale_project_baseline, re-inspect and create a new preview.
For operation_busy, retry the same operation ID after a short delay.
For an accepted or pending confirmation, call project_config_confirm_mutation again with the same operation ID.
For an expired preview with no durable operation, repeat the original preview request.
For an authorization error, stop and report the missing permission and target reach. Do not retry under the hosted daemon identity.

Guides

Core Concepts

Ions

Resources

Distributions

Tools

Other

Before you begin

Enable and connect

How changes work

Inspect a Project

Preview an Ion addition

Confirm the preview

Preview a batch

Tool reference

Project creation

Project deletion

Ion configuration

Models

Daemon identities

Common errors

Security and attribution

What to do next

Agent Instructions

Choose an integration path

Follow the Project mutation workflow

Build and deploy a LangGraph agent

Respect configuration boundaries

Handle daemon uniqueness and concurrent changes

Recover from stale or unavailable previews

​Before you begin

​Enable and connect

​How changes work

​Inspect a Project

​Preview an Ion addition

​Confirm the preview

​Preview a batch

​Tool reference

​Project creation

​Project deletion

​Ion configuration

​Models

​Daemon identities

​Common errors

​Security and attribution

​What to do next

​Agent Instructions

​Choose an integration path

​Follow the Project mutation workflow

​Build and deploy a LangGraph agent

​Respect configuration boundaries

​Handle daemon uniqueness and concurrent changes

​Recover from stale or unavailable previews

Before you begin

Enable and connect

How changes work

Inspect a Project

Preview an Ion addition

Confirm the preview

Preview a batch

Tool reference

Project creation

Project deletion

Ion configuration

Models

Daemon identities

Common errors

Security and attribution

What to do next

Agent Instructions

Choose an integration path

Follow the Project mutation workflow

Build and deploy a LangGraph agent

Respect configuration boundaries

Handle daemon uniqueness and concurrent changes

Recover from stale or unavailable previews