MCP Server Connection

Aether exposes an MCP server, so AI agents can report Deltas and request Trigger Plans as ordinary tools, without the Python SDK. Before you start: create a Connected System in the Aether Dashboard and copy its API key.

Server details


URL	`https://aether-mcp-production.up.railway.app/mcp`
Transport	Streamable HTTP
Authentication	`Authorization: Bearer <system_api_key>` header

The API key goes on the connection, never in a tool argument, so it stays out of the LLM’s context. Each connection speaks for the system that owns the key.

Connect your agent

Claude Code
Cursor
n8n

claude mcp add --transport http aether https://aether-mcp-production.up.railway.app/mcp \
  --header "Authorization: Bearer <system_api_key>"

In .cursor/mcp.json:

{
  "mcpServers": {
    "aether": {
      "url": "https://aether-mcp-production.up.railway.app/mcp",
      "headers": {
        "Authorization": "Bearer <system_api_key>"
      }
    }
  }
}

Create a Bearer Auth credential with the system’s API key as the token.
Add an MCP Client Tool node to your AI Agent.
Set the endpoint to https://aether-mcp-production.up.railway.app/mcp, the transport to HTTP Streamable, and select the credential.

Never commit a config file that contains your API key.

Available tools

`emit_delta`

Reports one event to Aether.

Argument	Type	Description
`event`	`string`	Event name, e.g. `"scan.completed"`.
`workspace_revision`	`string`	Revision of the workspace the event happened on.
`payload`	`string`	A JSON-encoded object, e.g. `"{\"findings_count\": 3}"`. Max 64 KiB.

Returns the Delta’s id and received_at. If the payload does not match the event’s contract, the tool returns an error telling the agent what to fix, so it can retry.

`trigger_plan`

Asks Aether which systems should run.

Argument	Type	Description
`intent`	`string`	Why you are asking, in plain words. Max 2000 characters.

Returns the Trigger Plan. Only the environment’s top-level orchestrator can call it.

Example prompts

When a Connected System is an AI agent, its system prompt tells it when and how to call the Aether tools. Adapt these examples to your agents.

Agent: emit_delta
Orchestrator: trigger_plan

An agent that reports what it did after finishing its work. Here, a newsroom writer.

After you finish writing or revising a draft, call the emit_delta tool exactly once:
- event: the event from your System Contract that matches what you did.
- workspace_revision: the revision you were given in the input.
- payload: a JSON-encoded object string that matches the event's payload_schema.

If the tool returns an error, read it, fix the arguments and call it again.
Never invent events or fields that are not in your System Contract.

Your System Contract:
{
  "capabilities": [
    {
      "code": "write_article",
      "description": "Writes or revises a draft from sources and verdicts.",
      "reads": ["sources", "verdicts"],
      "writes": ["drafts"]
    }
  ],
  "emit_events": [
    {
      "event": "draft.written",
      "kind": "COMPLETION",
      "payload_schema": {
        "type": "object",
        "required": ["draft_id", "revision", "title"],
        "properties": {
          "draft_id": { "type": "integer" },
          "revision": { "type": "integer" },
          "title": { "type": "string" }
        }
      }
    }
  ]
}

The top-level orchestrator, asking Aether which agents to wake.

You are the orchestrator of an automated newsroom. Before waking any agent,
call the trigger_plan tool exactly once, with the editor's request as the intent.
Never call it twice in the same run.

Then, for each system in the plan:
- RUN: wake the agent.
- SKIP: do not wake the agent.
- UNKNOWN or NO_DELTAS: Aether leaves the decision to you. Decide RUN or SKIP
  from the request and the agent descriptions below.

Agents:
- scout: polls the news feed and stores one new news item. Writes sources.
- writer: writes or revises drafts. Reads sources and verdicts, writes drafts.
- checker: fact-checks drafts not checked yet. Reads drafts, writes verdicts.
- illustrator: makes images for drafts without one. Reads drafts, writes images.

Waking an agent costs money. Wake it only when the request calls for its work.

Always include the system’s System Contract in the prompt of an agent that calls emit_delta. It lists the events the system may report and the schema of each payload, so the AI knows which event to send and how to build payload. Without it, the AI may invent events or send payloads that do not match the contract. Invented events are not rejected: they are added to the contract. Copy it from the system’s contract in the Aether Dashboard, with View JSON.

Troubleshooting

401 Unauthorized when connecting

The Authorization header is missing, is not Bearer, or the key is invalid, revoked or expired. Check the header and copy the key again, without stray spaces.

trigger_plan returns a permission error

Only the top-level orchestrator can request a plan. Connect with the orchestrator system’s API key.

emit_delta says the payload must be a JSON-encoded object string

payload is a string, not an object. Encode the object as JSON first, e.g. "{\"status\": \"ok\"}".

Payload rejected

The payload does not match the event’s contract. Fix the fields named in the error and retry.

Getting started

Important concepts

Aether

Server details

Connect your agent

Available tools

`emit_delta`

`trigger_plan`

Example prompts

Troubleshooting

​Server details

​Connect your agent

​Available tools

​emit_delta

​trigger_plan

​Example prompts

​Troubleshooting

Server details

Connect your agent

Available tools

`emit_delta`

`trigger_plan`

Example prompts

Troubleshooting