> ## Documentation Index > Fetch the complete documentation index at: https://docs.aion.to/llms.txt > Use this file to discover all available pages before exploring further. # Project MCP > Inspect and safely change Aion Projects and Ions through permission-checked MCP tools. The Project MCP server gives MCP clients a semantic, permission-checked way to inspect and change Aion Projects. It works with the [Ions](/docs/concepts/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](/docs/resources/mcp-resources) for OAuth, personal API-key, deployment credential, and client configuration guidance. ## Enable and connect 1. Open **Resources > MCP Servers**. 2. Select **Global**. 3. Find **Aion Project Configuration** and turn on **Enabled**. 4. Open the server and select **Usage**. 5. Choose **Direct server**, then copy the generated endpoint and configuration for your MCP client. 6. 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: 1. Inspect the current Project. 2. Call a mutation tool to create a preview. 3. Review the preview's summary, affected resources, required permissions, validation issues, target hash, and expiry. 4. Ask the user to approve the proposed change. 5. Call `project_config_confirm_mutation` with the preview's `operationId` and `confirm: true`. 6. 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: ```json theme={null} { "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: ```json theme={null} { "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: ```json theme={null} { "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: ```json theme={null} { "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: ```json theme={null} { "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: ```json theme={null} { "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](/docs/resources/mcp-resources) to configure a direct client or an Aion deployment. * Review [Roles & Permissions](/docs/concepts/roles-and-permissions) for Project reach and Identity assignments. * Open [Composer](/docs/composer) to inspect the resulting Project graph and checkpoint history.