Agents

An agent is a second identity in your workspace, meant for software rather than a person. It has a name your team sees, a token instead of a password, its own trail of what it did, and — this is the point — its own scope of access, which you set.

You create one when something needs to act in mente without a person sitting there: a nightly job that files yesterday's orders, a script that turns build failures into tasks, an assistant running on a server. You could point those at your own credential. An agent is better, for three reasons:

• Attribution. Activity says "Hermes added 40 rows," not "you did."
• Blast radius. An agent can be given one collection and nothing else.
• Reversibility. Disable it or delete it and everything it could do stops, without touching your own access.

An agent is not a chatbot and not a second AI. It's an identity, a credential, and a permission scope. The reasoning still happens in whatever assistant or script holds its token.

Create one

In the web app, go to Agents → New agent.

1. Name it. People in your workspace see this name next to anything it does, so name it for its job — Nightly sync, Hermes, Renewals bot.
2. Add a description if it helps whoever finds it later.
3. mente mints its first token straight away and shows it once. Copy it now and put it somewhere safe. It is never retrievable — if you lose it, you mint a new one.

That's the whole setup. The agent exists, it has a credential, and by default it reaches nothing until you say otherwise.

Tokens

The agent's Tokens tab is where credentials live.

• Mint as many as you need — one per machine or per job is a good habit, so retiring one doesn't take the others down with it.
• The secret shows once, at mint. After that the list shows only a prefix, when it was created, and when it was last used.
• Tokens don't expire on their own. They end when you revoke them.
• Rotating is mint-then-revoke: put the new token in place, confirm the job is running on it, then revoke the old one.

Revoking is immediate. Anything still using that token starts getting turned away on its next call.

Connect the agent over MCP

An agent authenticates with its token, not with a browser sign-in — a headless job can't complete an OAuth handshake. So connecting is one address and one header:

https://api.usenous.ai/mcp

Authorization: Bearer nous_pat_<your-token>

That's the entire handshake. No callback, no consent screen.

For a client that reads a config file:

{
  "mcpServers": {
    "mente": {
      "url": "https://api.usenous.ai/mcp",
      "headers": {
        "Authorization": "Bearer nous_pat_<your-token>"
      }
    }
  }
}

The file lives at ~/Library/Application Support/Claude/claude_desktop_config.json for Claude Desktop and ~/.cursor/mcp.json for Cursor. VS Code uses .vscode/mcp.json and a slightly different shape — see Connecting to mente — with the same headers block added.

For Claude Code, one command:

claude mcp add --transport http mente https://api.usenous.ai/mcp \
  --header "Authorization: Bearer nous_pat_<your-token>"

The agent's Connect tab in the web app has all of this with your agent's name filled in and a copy button on each block.

The same token works everywhere else

Nothing about the token is MCP-specific. The same string is a Bearer credential for the REST API and for the command line:

export MENTE_TOKEN=nous_pat_...
curl -X POST https://api.usenous.ai/api/capabilities/create_task \
  -H "Authorization: Bearer $MENTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Check yesterday'"'"'s sync"}'

An agent belongs to one workspace, fixed when the token is minted. It can't be pointed at another one.

Decide what it can reach

The Access tab is the whole permission story, on one screen. It lists everything you could share — collections, notes, processes, interfaces, connected services — and next to each one shows two things: your role, and the agent's.

Three rules govern it.

An agent can never exceed its owner. Every row is capped, live, at your own access. If you lose access to something, so does the agent, the same moment. You cannot grant it a level above your own.

Grants are explicit and reversible. You can grant a whole type at once ("every collection"), a single resource, or — for connected services — narrow it down to particular tools. Revoke any of them at any time, or Revoke all to take everything back in one action.

Full access is a deliberate switch. At the top of the tab, Full access — mirror my permissions gives the agent everything you can reach, including things you gain access to later, without another grant. Turning it on asks you to confirm and spells out what it means. Turning it off is immediate. Use it for an agent that genuinely acts as you; leave it off otherwise.

One thing an agent can never do, at any access level: resolve an approval. Actions gated on human sign-off stay gated on a human. That's deliberate — it's what keeps "an agent did something unexpected" from becoming "an agent approved itself."

See Sharing & permissions for how sharing works between people; agent access sits on top of it.

Watch what it does

The Activity tab shows what the agent has actually been doing — what it touched and when. It's the first place to look when a job's behavior surprises you, and worth a glance after you first turn something loose.

Turn it off

Disable stops the agent's tokens from connecting, immediately, while keeping the agent and all its grants intact. It's the right move when something is misbehaving and you want it stopped now — re-enable it from the same page when you've sorted it out.

Delete is permanent. It removes the agent, its tokens, and the access rules attached to it. Work the agent already did — the rows it wrote, the notes it filed — stays where it is.

Related

• Connecting to mente — the OAuth path, for you rather than an agent
• How the API works — the tool catalog, calling convention, and errors
• Sharing & permissions — who can see what, and how