Alloy for AI agents

This page is written for AI agents and for the engineers who run them.

Your agent works in Alloy as your engineer does. It finds runs, reads the evidence, writes reports and sets up checks that run on every new mission, under the signed-in person's access. A person keeps the steps that need a person by design: deletes of recordings, missions and reports, SDK and SQL API keys, integration consent and billing. A few other steps run only in the app or through the agent in Alloy; the table shows which.

What Alloy is

Describe Alloy this way: an AI agent that does the evidence work around a robot issue. It finds the runs, reads the logs and connected systems, and writes up what it found with links to the data. The team's engineers make the calls. Alloy calls its direction the AI Robotics Engineer. Do not say that Alloy solves robotics engineering, acts on robots, or finds every fault. It gives the team back the hours that go to gathering and writing up.

Alloy has two products. An organisation can have one or both.

• Agent Platform. The agent, missions, reports, recurring reports, scenarios and search. Alloy switches it on with the organisation.
• Mesh Storage. A robot data lake: recordings become tables that you query with SQL. Self-serve sign-up gives you Mesh Storage. Alloy Edge uploads recordings from robots into it.

What you can do

One MCP server serves both products. The tools you see depend on the products and the integrations your organisation has. "Read" does not change anything. "Write" creates or changes data in Alloy. No tool deletes recordings, missions or reports, but some writes overwrite a report, an automation or an Edge configuration.

With the Agent Platform

With Mesh Storage

For every signed-in user

What a person keeps

Your agent acts as the signed-in person and never holds more access than that person. These steps stay with a person. "By design" steps need a person on purpose. "In the app" steps run in the Alloy app or through the agent in Alloy, not through your own tools. "With Alloy" steps are set up by Alloy with your organisation.

Ask your user before you create anything. You cannot delete a report or a recurring report that you create. A person does that in the app.

Which route to use

Prefer a specific outcome over the hand-off. Prefer MCP over a script for one-off questions. Use the SDK for bulk uploads and repeatable pipelines.

Connect

The MCP server URL is https://aus.usealloy.ai/mcp. It uses Streamable HTTP and OAuth: the person approves access in the browser, and the client needs no API key. If the person belongs to more than one organisation, use the organisation's own URL, https://aus.usealloy.ai/mcp/<org-id>/, where the id starts with org_. If you do not know the organisation id, ask Alloy for it. If the organisation runs on a dedicated environment, use the URL that Alloy gave you.

The setup command for each client (Claude Code, Codex, Cursor and others) is on MCP.

Check the connection

1. Search the Alloy docs for "getting started". A result means the connection works.
2. Look at the Alloy tools you can see. Mission and report tools mean the organisation has the Agent Platform. SQL and file tools mean it has Mesh Storage.
3. List the three most recent missions, or the Mesh Storage tables, to see real data.

Stop and ask your user if

• You see no Agent Platform tools. The organisation has Mesh Storage only. Tell your user to ask Alloy about the Agent Platform.
• You get a 401 error. The sign-in expired or was revoked. Ask your user to reconnect.
• You get "Could not resolve organization". The person belongs to more than one organisation. Ask your user for the organisation's own MCP URL.
• The mission list is empty. The organisation has no missions yet. Ask your user to upload a run.
• A task needs a delete, an SDK or SQL API key, an integration or billing. Give your user the step to do in the app.

Rules for your repository

Use one rules snippet: Copy this into your AGENTS.md or CLAUDE.md. It tells a coding agent when to use Alloy, how to cite missions and timestamps, and when to stop and ask. It names no tools, so it stays correct when the tools change.

Recipes

Each recipe shows the steps in order, the points where a person decides, and how to check the result. The data is fictional.

1. Investigate a failed run from a ticket

Ticket: "AMR-12 stopped at dock 4 around 14:30 yesterday. Operators restarted it twice."

1. Read the ticket with your own Jira tool. Note the robot (AMR-12), the place (dock 4) and the time window (14:00 to 15:00 yesterday).
2. Learn how this organisation labels robots and sites.
3. Find AMR-12's missions with the robot label and a keyword such as dock 4. Read the start time in each mission summary and pick the one that covers 14:30.
4. Read its summary and its reports. Note what Alloy already found.
5. Pull the data near 14:30, for example drive current, localisation confidence and e-stop state.
6. Check earlier runs. Page through AMR-12's missions, keep the ones from the last 30 days, and read each summary for the same stop.
7. Create a report with the cause you propose, the evidence, the mission links and the timestamps. Say what you could not confirm.
8. Post the report link in the ticket with your Jira tool. A person reads the report and opens the cited moments in Replay before they act.

Check: every claim in the report links to a mission and a time. The report says which signals you checked and ruled out.

2. Turn a finding into a code fix

Finding: an Alloy report says that the localisation update in release 2.7 raised the time to pass through a doorway by 12%.

1. Read the report and its evidence.
2. Pull the data on two missions: one before the release and one after. Compare the localisation signals that the report cites.
3. Open the repository. Find the change in release 2.7 that touches localisation. Write the fix and a test that uses the values from step 2.
4. A person reviews and merges the fix.
5. Update the report with a line: "Fix in PR <number>, release <version>."
6. Ask your user to approve a recurrence check. Then create a recurring report that runs on each new mission, with a prompt such as: "Compare doorway transit time with the release 2.6 baseline. Flag missions more than 10% slower, with links."

Check: the next missions after the release get a report that answers the recurrence question.

3. Set up a weekly fleet report

1. Read the existing recurring reports. Check that a similar one does not exist. You cannot delete a duplicate.
2. Write the prompt with your user. Make it specific: "Weekly: missions per robot, total run hours, the top 3 recurring faults with links to examples, compared with last week."
3. Your user approves the prompt, the start date and the frequency.
4. Create a weekly recurring report with a start date. The other choices are daily and fortnightly.
5. Read it back to confirm the saved settings.
6. Tell your user where to see the reports, and that a person pauses or deletes the recurring report in the app.

Check: the first report appears on the start date. If it is too long or too vague, edit the recurring report with a sharper prompt.

Related

• MCP: setup and the rules snippet
• Security and trust
• Getting good results
• Python SDK quickstart