aeon


aeon developer resources.

The API, the MCP servers, and everything an agent or developer needs to call aeon.

aeon is an open-source framework you own and run on your own GitHub Actions - there is no hosted CRUD API - but it does expose a small set of real, reachable endpoints for agents and developers, all described here at predictable URLs. The one way to drive your own agent remotely is the Aeon Connect MCP server.

API & endpoints

The full, typed description of every reachable endpoint lives in the OpenAPI 3.1 spec (function-calling ready: unique operation IDs, typed schemas, descriptions). The two input-driven endpoints:

  • /ask - the NLWeb natural-language endpoint. POST { query } (or GET /ask?q=...) to get ranked schema.org resources from aeon's pages and live skill catalog. Add prefer: streaming=true for Server-Sent Events.
  • /mcp - the public, read-only aeon docs MCP server (see below).

aeon docs MCP (read-only)

aeon runs a public, read-only Model Context Protocol server over Streamable HTTP at https://www.aeon.fun/mcp. Point Claude, ChatGPT, Cursor, or any MCP client at that URL and it can call aeon's read-only tools natively - an overview, the setup command, the skill catalog, keyword search, and a list of aeon's resources. The server card is published at /.well-known/mcp.json. It only reads public docs. To drive your own agent, use the Aeon Connect MCP server below.

Aeon Connect MCP (drive your own agent)

Aeon Connect serves a remote MCP server at https://www.aeon.fun/connect/mcp (Streamable HTTP, OAuth). Sign in with GitHub, pick which of your aeon agent repos to use, and your MCP client can list and run skills, follow runs, read output, memory, strategy and soul, turn skills on or off, check setup, and install packs. Runs still happen on your own GitHub Actions, and keys are never passed through chat.

One-click install: Cursor · VS Code · Kiro · LM Studio. Registry name: fun.aeon/aeon.

# Claude Code
claude mcp add --transport http aeon https://www.aeon.fun/connect/mcp
# Codex CLI
codex mcp add aeon --url https://www.aeon.fun/connect/mcp
# Gemini CLI
gemini mcp add --transport http aeon https://www.aeon.fun/connect/mcp
# VS Code
code --add-mcp '{"name":"aeon","type":"http","url":"https://www.aeon.fun/connect/mcp"}'

In ChatGPT, Claude or Grok (Connectors, New, Custom), add it as a custom connector with that URL, then sign in when asked. Le Chat, Perplexity, Gemini, Notion, Copilot Studio and Amazon Quick take it the same way, and it works in any other MCP client too. To run it locally over stdio instead, use the aeon-mcp server in apps/mcp-server and register it with bin/add-mcp.

Aeon Connect (hosted dashboard)

Aeon Connect is the hosted, multi-tenant aeon dashboard: sign in with GitHub, create an instance (a public fork or a private copy of aeonfun/aeon), connect a model, pick skills, and drive runs from the browser. It talks to GitHub through the Aeon Connect GitHub App with tokens scoped to the one repo you pick, and stores keys only as encrypted secrets in that repo. It is also the reference implementation of the ADK pattern for building products on aeon.

CLI

Every aeon instance is driven by its own ./aeon CLI in its repo: authenticate, pick skills, and schedule them from the command line. aeon also ships as an installable Claude Code plugin from the plugin/ directory of the source repo.

Machine-readable discovery

Agent-facing files an agent can fetch directly:

Authentication & rate limits

The reachable read-only endpoints (/ask, /mcp, and the discovery documents) need no authentication - everything they return is public. Every response carries standard RateLimit headers (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy); the soft limit is 120 requests per 60 seconds per client, and /ask answers a 429 with a Retry-After header when it is exceeded. Unknown /api/* paths return a structured JSON 404. The Aeon Connect MCP server at /connect/mcp is the exception: it acts on your own agent, so it needs an OAuth sign-in with GitHub first.

API versioning

The reachable API is v1, versioned in the URL path - https://www.aeon.fun/v1/ask is the versioned alias of /ask - and echoed in an API-Version response header on every API response. Breaking changes ship under a new version prefix (/v2/…); the previous version keeps working through its sunset window.

Deprecation & sunset policy

When an endpoint is deprecated, aeon signals it two ways so an agent can plan around it:

  • a Deprecation response header carrying the date the endpoint was deprecated (RFC 9745); and
  • a Sunset response header carrying the date it will be removed (RFC 8594), with a Link header (rel="deprecation") pointing back to this page.

There is a minimum of 90 days between the Deprecation and Sunset dates. Nothing is deprecated today, so neither header is emitted. This policy, along with the versioning and rate-limit conventions, is also declared in the OpenAPI spec (the x-api-versioning, x-deprecation-policy, and x-ratelimit extensions).

Errors

Every agent-facing endpoint returns structured JSON errors, never an HTML page, so a failure is parseable: { "error": { "code", "message", "hint", "docs" } }. The docs field links to the matching entry below.

  • invalid_json (400) - The request body is not valid JSON.
  • missing_query (400) - POST /ask was called without a non-empty query.
  • not_found (404) - No API endpoint exists at the requested /api/* path.
  • method_not_allowed (405) - The MCP server was asked for a server-initiated SSE stream it does not offer.
  • rate_limited (429) - The per-client rate limit was exceeded. Wait for Retry-After seconds.



RUN NOW