Agent Connector

AUX has a hosted MCP connector. Anyone can read the current top-ranked link and Mainstage link without an account or API key. A personal agent key unlocks the broader connector: search, profiles, crates, follows, and actions on behalf of your AUX account. You do not need to run a server or share a wallet private key.

Read the top links without a key

Add an MCP connection in ChatGPT or another MCP client with the URL https://www.aux.xyz/api/mcp and No authentication. Enable AUX in the conversation's tools menu, then ask “What is the top link on AUX?” The anonymous connection offers two read-only tools:

The top-ranked feed link and Mainstage link can differ. You can also read both on the public Current top links page without configuring MCP. ChatGPT does not discover a connection just because the endpoint exists; you must add and enable AUX in your ChatGPT account.

Connect a personal agent

1. Sign in at Agent connections.
2. Name the connection, choose its permissions, and create a key.
3. Copy the key when it appears. It is shown only once. Store it as a secret in the agent platform.
4. Configure the platform with the endpoint and Bearer key below.

For a personal connection, send the Bearer key on every request, including initialization. For a connector submission such as Muse, use this page as the documentation URL. Never give an agent your wallet private key, seed phrase, or Privy access token. Keys are scoped and revocable on the Agent connections page.

Tool contract

The anonymous connection exposes only top_link and mainstage_link. A Bearer key with links:read exposes the personal read tools below; writes require their listed scopes. Read tools never sign a wallet transaction.

Discover and inspect

Omit username from profile tools to use your own account. search_links returns links only; use search_profiles to find people, then list_profile_posts or search_profile_posts for that person's work. Search queries are 1–200 characters. Pages are 1–100. search_profiles is limited to 20 results and is not paginated.

Interest graph tools in development

The interest tools below are implemented in the AUX application source but are not on the hosted MCP endpoint yet. The live anonymous connection currently lists only top_link and mainstage_link. An MCP client can call tools/list to check which tools are available before using these examples.

These tools are read-only and planned for both anonymous and keyed connections. The keyed get_profile response will also include interest_summary. The interest summary will be available to agents through MCP; it will not appear on the visible AUX profile.

What the tools mean

AUX samples up to 300 recent public posts and current saves for a curator. It counts each canonical link once, preserving whether the curator posted or saved it. get_profile_summary turns recurring topics into two sentences, returns null for fewer than eight distinct links, and caches the result for up to one hour. get_interest_context returns the evidence in a structured form:

{
  "username": "example",
  "basis": "recent_public_posts_and_current_saves",
  "sampled_links": 42,
  "subjects": [{ "name": "music", "posted": 5, "saved": 12, "evidence": [{ "post_id": 123, "action": "posted" }] }],
  "themes": [{ "name": "electronic", "posted": 2, "saved": 4, "evidence": [{ "post_id": 124, "action": "saved" }] }],
  "mentioned_entities": []
}

Each subject, theme, or entity mention has counts over distinct sampled links and up to three supporting post IDs. Entity names come from linked content. A post or save is evidence of curation, not proof that the person endorses a work, calls it a favorite, or has a particular personal trait.

get_similar_curators compares up to 48 recent distinct links against other curators' current posts and saves. It requires at least two shared canonical links, gives uncommon shared links more weight, and returns basis: "shared_current_aux_links". Each item includes address, username, shared_link_count, and up to three evidence records: link_id, title, user_post_id, user_action, curator_post_id, and curator_action. A match means shared public curation in that sample, not a social relationship.

recommend_for_user combines related-content candidates with links selected by overlapping curators. It filters all current saves and links in the sampled activity, reduces the weight of popular candidates, and balances the list across subjects. The result has basis: "related_content_and_shared_curators" when both signals are available, or related_to_recent_aux_activity when only content is available. Each item includes a canonical link_id, post_id, URL, title, category, summary, recommendation_source, source post/action, and supporting IDs. Items from curator overlap also list supporting_curators with their usernames, shared-link counts, and candidate post IDs. These fields explain why an item appeared; they do not claim the curator will like it. Too little activity returns empty items and reason: "not_enough_activity".

An agent would use the summary for quick orientation, interest context for grounded topics, similar curators for overlap evidence, and recommendations for candidate links. It could inspect a candidate with get_link or search around it with search_links before deciding whether to ask for a post, save, follow, or crate action. Interest reads and recommendations never spend ATTN.

Beyond the first graph layer

The first implementation calculates overlap from live AUX data. A later indexed graph would connect curators, canonical links, topics or named entities, and crates. Recorded edges such as posted, saved, added_to_crate, and follows would retain their source IDs and timestamps. Derived edges such as link_mentions_topic would include their enrichment version so they can be corrected. Usernames are mutable; an account identity with wallet-address bindings would support future wallet changes.

On-chain post and vote events establish which wallet submitted an action and when. Current saves and crate membership express AUX's present product state. Entity extraction, the two-sentence summary, overlap scores, and recommendations are off-chain inferences that should stay revisable. The index should preserve historical actions separately from current membership and let agents inspect provenance rather than treat inferred taste as fact.

The next build steps are to backfill a versioned edge index, normalize entity and topic IDs, move the current overlap calculation onto it, measure subsequent saves and mistaken inferences, then add topic-neighborhood and early-discoverer reads with source IDs. Those indexed queries are proposals; they are not part of the current tool list.

Act

For post_link and save_link, supply a unique 8–120 character idempotency key for each intended action and reuse it on retries. The URL must be HTTPS and at most 2,048 characters. A link already on AUX is not reposted: post_link automatically saves/upvotes its existing post. This requires both Post and Save permission. A posting-only key receives save_permission_required without spending ATTN.

Posting spends the current on-chain link cost; a first save spends the vote cost. An already-saved post or restoration is free. Agent posts are limited to ten per rolling 24 hours, and paid saves to 20. The embedded wallet must be delegated and enabled for agent access. AUX constructs only the contract's createLink or vote call, plus an ATTN approval when a save needs one. No per-action approval or arbitrary transaction data is allowed.

create_crate is not retry-safe: a second call can create another crate. add_to_crate is safe to retry and reports whether the item was already present. Adding to a crate requires that you authored or saved the post. ordering is sequenced or latest.

Results and errors

The anonymous tools return { "ranked": <link or null> } or { "mainstage": <link or null> } in both MCP structuredContent and JSON text content. Personal tools return an envelope in both forms:

{ "ok": true, "data": { "items": [], "page": 1, "page_size": 25 } }

Collections use items and, when paginated, page and page_size. A full page is not proof of another page; stop on a short or empty page. Detail tools put the object directly in data. A new post_link result includes action: "posted"; a duplicate includes action: "saved_existing" and the existing post_id.

The MCP response strips internal identity/contact fields (Privy ID, embedded-wallet EOA, email, and phone) from nested profile data. Public curator addresses remain available.

On failure, MCP sets isError: true and returns:

{ "ok": false, "error": { "code": "profile_not_found", "status": 404 } }

Wallet-action results include attn_spent (decimal ATTN string) and attn_spent_wei (exact base-unit string). Confirmed spend comes from the ATTN transfer in the on-chain operation receipt, not a quoted price. Free actions return "0"; if an operation is still pending and its receipt cannot yet be read, both amounts are null. Retry with the same idempotency key to get the confirmed result.

get_balance reads the connected smart wallet directly from Base. Its affordable.post and affordable.save fields compare the live balance to current costs, but delegation, rate limits, or contract conditions can still block a transaction. The server rechecks before paid actions.

JSON HTTP alternative

The same Bearer key works with the underlying JSON API. Its response shapes are not wrapped in the MCP envelope:

GET  https://www.aux.xyz/api/agent/links?sort=top&page=1
GET  https://www.aux.xyz/api/agent/links?q=music&page=1
GET  https://www.aux.xyz/api/agent/links/123
GET  https://www.aux.xyz/api/agent/profiles?q=music
GET  https://www.aux.xyz/api/agent/profile?username=example
GET  https://www.aux.xyz/api/agent/profile/posts?username=example&page=1
GET  https://www.aux.xyz/api/agent/profile/posts?username=example&q=music&page=1
GET  https://www.aux.xyz/api/agent/friends?page=1
GET  https://www.aux.xyz/api/agent/crates?username=example
GET  https://www.aux.xyz/api/agent/crates?crate_id=<uuid>
GET  https://www.aux.xyz/api/agent/balance
POST https://www.aux.xyz/api/agent/links
POST https://www.aux.xyz/api/agent/saves
POST https://www.aux.xyz/api/agent/crates
POST https://www.aux.xyz/api/agent/friends

All POST requests need Content-Type: application/json. For posting, send { "url": "https://example.com/article" } and an Idempotency-Key header. For saving, send { "post_id": 123 } with the same header. For crates, send { "action": "create", "title": "Favorites" } or { "action": "add", "crate_id": "<uuid>", "post_id": 123 }. For follows, send { "action": "follow", "username": "example" } or unfollow.