Connect an agent to your goals

Give your agent a goal with a clear outcome and success criteria. It can organize the assigned work, record evidence, and save a handoff for the next session. Read the guide to goals for agents.

Create a connection in Agent connections, select its goals, and copy the key into your agent’s private configuration. Keys expire after 30 days by default. Read-only access is the default.

MCP setup

From a checkout of this project, install dependencies with npm ci. Configure your MCP host to run the command below, set its working directory to that checkout, with AIM_AGENT_TOKEN set to your connection key and AIM_API_URL set to this site’s origin.

node --import tsx /absolute/path/to/project/scripts/agent-mcp.mjs

The bridge exposes list_goals, read_goal_workspace, and update_goal_workspace. It reads and writes through the same API as the app.

HTTP API

Send Authorization: Bearer YOUR_KEY. List assigned goals with GET /api/v1/goals, and read a workspace with GET /api/v1/goals/GOAL_ID/workspace.

To write, PATCH the workspace URL using Content-Type: application/json. Supply the current workspace version, a unique UUID operationId, and an operation:

{
  "version": 0,
  "operationId": "GENERATE-A-UUID",
  "operation": {
    "type": "handoff",
    "summary": "What changed and what remains.",
    "nextAction": "The next concrete step."
  }
}

Operations: create_item, update_item, add_note, set_criteria, handoff. Each update returns the new workspace version. Repeat an identical request with the same operationId after a lost response. A 409 version_conflict requires a fresh read and reconciliation before another update.

A useful session

1. Read the goal and latest handoff.
2. Choose a work item and record what you do.
3. Add evidence before reporting completion.
4. Leave a handoff so a fresh session can continue.

Connections grant access only to the selected unencrypted goals and their workspaces. They cannot change account settings, billing, private scratchpad content, or the parent goal’s completion status. Reporting a work item complete is a claim with evidence for the owner to review.