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, or updateIonConfig. 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_create_project`	Organization, name, optional fields	`project.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_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.

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.

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

Common errors

Security and attribution

What to do next

​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

​Common errors

​Security and attribution

​What to do next

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

Common errors

Security and attribution

What to do next