Working with the OpenX MCP tools

This page answers how an agent should work with the OpenX MCP server. Every agent gets the same guidance: Claude Code, any other MCP client, and Azi, the assistant built into OpenX. The server sends it as its instructions when a client connects, and as the posture prompt for a client that reads prompts (see Prompts).

Act when the ask is clear

When the ask is clear, call the tool that answers it, then say what you did and offer the next step. Ask only when the ask is truly ambiguous, and then ask one question.

call_api already knows the address

call_api already knows the workspace's api address and signs in as you. Never ask a person for a base URL, a host, a port or a token.

• call_api with route "" lists the routes you may call, each with the query keys it declares.
• A saved warm query has its own route, such as GET /warm-queries/signups-per-hour. To run it, call that route. See Recipes for the full sequence.

What is in this workspace?

1. get_workspace for what is declared: every kind the workspace holds, and the pending proposals under ProposalGroups.
2. retrieve_inventory for what exists outside: locations, containers, device ids and drift.
3. Name every kind present, not only the first one you find.

Where to put a new node

A node on the canvas sits at Metadata.Position { X, Y }, its top left corner, and is drawn 250 wide and 56 tall. On a surface's canvas the surface's own entry for the node comes first. The Canvas page has the details. Before you propose a node with manage_proposals:

1. Read where nodes sit with get_workspace: each record's Metadata.Position, each surface's own entries, and each pending proposal's Proposed.Metadata.Position.
2. Lay the canvas out left to right in the direction data flows. Give the new node a Proposed.Metadata.Position one column (300 on X) right of what feeds it, in the first row (120 on Y) clear of every node and every pending proposal. Never copy another node's position.
3. Run manage_proposals with checkOnly: true and read its layout warnings: nodes that overlap, lines that cross, nodes with no position. Each names a free spot. Move the node, then submit.

No code places a node for you: a node proposed with no position is drawn at the top left, where it can cover another node. manage_proposals refuses a position in the two places the canvas never draws: Proposed.Details.Metadata and the proposal's own Metadata.Position.

If nodes near your work already overlap or have no position, you may propose new positions for them as ordinary updates in their own group named Tidy the canvas. A person accepts it.

The tools listed are the ones you have

The tools the server lists are the ones you have now. An earlier answer in the conversation that said a tool was missing, or that an address was needed, does not hold.