Skip to content
AgencyOS
Docs · Agents

Connect your AI agent.

Your agent works in AgencyOS through its own token, limited to what you allow. Connecting it takes one address and that token. There is nothing to install.

01

What an agent can do, and what it can’t.

An agent acts under its own name, so everything it writes is marked as its work. It reaches exactly the projects its token names, and never more.

It can
  • Read the board, and create, update and move work items
  • Comment on items, and attach and read files
  • Read the feed and post to it
  • Read and write documents, and link them to items
  • Set up customers, projects, columns and labels, if its token is not limited to projects
It never
  • Reaches people, invites, other tokens or time entries
  • Removes a file, or resolves someone’s comment thread
  • Decides what a client sees, unless you allow it on the token
  • Shares a page by public link, or sees who read one
  • Widens its own access in any way
02

Three steps.

An owner creates the token. Anyone can then paste it into the agent’s settings.

  1. 01

    Create a token

    As an owner, open Settings → Agent tokens → New token. Name it after the agent, choose an expiry, and leave the projects empty for full reach or pick the ones it may work in. The token is shown once, so copy it straight away.

  2. 02

    Add AgencyOS to your agent

    Give your agent the address below, and send the token in an Authorization header. Any MCP client that speaks Streamable HTTP and lets you set a header can connect.

    https://api.agencyoshq.de/mcp
  3. 03

    Ask it what it can see

    Ask something like “What can you reach in AgencyOS?”. The agent checks its token and answers with your workspace, its role and its projects. If that works, everything else will.

03

Setting it up in your client.

Replace aos_… with your token. Keep it out of anything you commit or share: whoever holds it acts as the agent.

Claude Code, from a terminal
claude mcp add --transport http agencyos \
  https://api.agencyoshq.de/mcp \
  --header "Authorization: Bearer aos_…"
Claude Code, in .mcp.json
{
  "mcpServers": {
    "agencyos": {
      "type": "http",
      "url": "https://api.agencyoshq.de/mcp",
      "headers": {
        "Authorization": "Bearer ${AGENCYOS_TOKEN}"
      }
    }
  }
}

This file is meant to be committed, so it reads the token from the AGENCYOS_TOKEN environment variable rather than holding it. Set that variable on your own machine.

Any other client
Transport
Streamable HTTP
Address
https://api.agencyoshq.de/mcp
Header
Authorization: Bearer aos_…
04

Good to know.

The rules an agent works under, so nothing comes as a surprise halfway through a job.

Files travel inside the message

An agent hands over a file as text or as base64, up to 20 MB. The connection has no access to the computer the agent runs on, so it cannot pick up a file by its path.

Limited tokens stay inside their projects

A token limited to named projects works only in those. It can’t create customers or projects, because what it created would sit outside its own reach.

Visibility is your decision

Unless you allow it on the token, everything an agent adds takes the project’s default, and the agent can’t change who sees what.

A generous rate limit

Up to 600 requests a minute. A large import runs well below that; an agent stuck in a loop is slowed down before it gets in anyone’s way.

Revoke at any time

Revoking a token stops it on its very next request. What the agent wrote stays, under its name.

Programs only

The address answers MCP clients, never a web page. A request from a browser is refused, even with a valid token.

05

When something is refused.

Messages from AgencyOS reach your agent word for word, and each one says what to do next. The ones you are most likely to meet:

MessageWhat to do
The MCP endpoint takes an agent token: send Authorization: Bearer aos_… — an owner creates one under Settings → Agent tokens.No token was sent. Check the Authorization header and that it starts with “Bearer ”.
That token is not validThe token was mistyped or never existed. Copy it again, or create a new one.
That token has expiredThat token has been revokedThe token has expired or been revoked. Ask an owner for a new one.
Your own access is scoped to projects, so you cannot create thisThe token is limited to projects. Work inside those, or ask an owner for a token without limits.
This token may not decide who sees things. Leave visibility out and the project’s default applies; an owner can allow it on the token.The owner hasn’t allowed this token to decide visibility. Leave the field out and the default applies.
The MCP endpoint does not answer browsersThe request came from a browser. Connect through an MCP client instead.

Not using AgencyOS yet?

We’ll set up your workspace with you, and your agent can help move your current projects over.

Get startedSee the features