# Using the API from an AI agent

Connect an AI app through MCP, build an agent on the SDKs, or give any agent one link, a token limited to what it should do, and the rules that keep it from doing harm.

Source: https://docs.orbits.africa/api/ai-agents

An AI agent can manage your apps through this API the same way a script does. There are three ways in, easiest first.

## Connect an AI app with MCP

If your AI app or editor speaks MCP, connect it to the Orbits MCP server:

```text
https://mcp.theorbits.app/mcp
```

It gives the app ready-made [tools](https://docs.orbits.africa/ai/mcp-tools) for projects, deployments, logs, variables and domains, and anything that changes production or deletes something asks you first. Step-by-step setup for each app, and how to run the server on your own machine instead: [Connect your AI](https://docs.orbits.africa/ai/connect-your-ai).

## Build your own agent on an SDK

Writing the agent yourself? The [SDKs](https://docs.orbits.africa/sdks) for JavaScript (`@useorbits/sdk`), Python (`useorbits`) and Go handle idempotency keys, safe retries, pagination and waiting for deployments, so your tools only describe what to do.

## Any other agent

For an agent that can only make HTTP calls, the rest of this page is what to give it, and what to tell it.

## Give it one link

The [agent brief](https://docs.orbits.africa/agent-brief.md) is everything an agent needs in one Markdown file: the base URL, how to authenticate, the rules it must follow, common jobs step by step, and every endpoint with the token it needs, its parameters and what it returns. It is generated from the API's contract, so it is always current. Agents that read OpenAPI can take the [contract](https://docs.orbits.africa/openapi/orbits-api.yaml) too, and the whole site is in [/llms.txt](https://docs.orbits.africa/llms.txt) and [/llms-full.txt](https://docs.orbits.africa/llms-full.txt).

## Give it a token for the job

Make a token for the agent alone, under **Team › Settings › API tokens**, with as little as the job needs:

- **Read** access if it only has to look: a `read` token can't change anything and never sees environment variable values.
- **One project**, if the job is about one project.
- **An expiry** of 30 days, rather than never.

Revoke it when the job is done. A token can never manage tokens, members or the team's security, so an agent can't give itself more access. See [Authentication](https://docs.orbits.africa/api/authentication).

## Tell it the rules

Put these in the agent's instructions, or check that its brief covers them:

1. Ask before anything that changes production or deletes: promoting, rolling back, pausing or deleting a project, deleting domains, variables or flags.
2. Treat variable values as secrets: reveal or pull them only when asked, and never print or log them.
3. Send an `Idempotency-Key` on the `POST`s that take one, and the same key when retrying ([Conventions](https://docs.orbits.africa/api/conventions)).
4. Follow `next_cursor` to the end of a list before deciding something doesn't exist.
5. On `429`, wait `Retry-After` seconds; on a `4xx`, fix the request instead of repeating it ([Errors](https://docs.orbits.africa/api/errors)).
