Build an agent

An agent on Msharti is not a separate product you configure. It is three things joined together: a credential that says who is calling, a role that says what that caller may do, and an allowlist of tools that says exactly which operations are on the table. Build those three and the agent is governed by construction.

The model

Credential = identity

Either an OAuth connection, in which case the agent runs as a named person, or an API key, in which case it runs as itself. Both are revocable independently of everything else.

Role = policy

Every credential carries exactly one role. The role is where the decision lives, so changing what an agent may do never means reissuing its credential.

Allowlist = capability

A role names the individual tools it permits, by tool name, such as mpesa_collection_summary. Anything not named is refused at the gateway, whatever the prompt says.

ℹ️

Why the allowlist is on tools and not connectors. "Can use M-Pesa" is not a useful permission, because M-Pesa can both read a collection summary and send money. The interesting boundary runs through the middle of a connector, so that is where the control sits. See read tools and write tools.

Building one, end to end

A worked example: a finance reporting agent that reconciles M-Pesa collections against Sage and checks supplier tax compliance. It must read those three systems and must never move money.

Connect the systems it needs. In the console open Connectors and configure M-Pesa, Sage and KRA. An agent cannot be granted a tool on a connector that is not configured, so this comes first.
Create the role. Roles & Access → New role. Name it for the job it does, not the person who asked for it: Finance reporting ages better than Wanjiku's agent.
Choose the tools, deliberately. The tool catalogue is fetched live from the gateway, so you are picking from what actually exists rather than from a list someone typed. Select the read tools this job needs. Leave mpesa_b2c_payment, mpesa_remit_tax and mpesa_reverse_transaction unselected. That omission is the whole control.
Issue the credential. For a person-driven agent, have them connect their assistant with OAuth and assign them this role on their seat. For an unattended agent, go to Settings → API Keys → New key, pick the assistant type, and bind this role to it. Copy the key; it is shown once.
Point the assistant at the gateway. One URL, https://mcp.msharti.dev/mcp. Per-assistant instructions are in Connect your AI.
Verify the boundary, not just the happy path. Ask it to do the job: it should work. Then ask it to send money: it should refuse, and the refusal should appear in the audit log as a denial. An agent you have only tested on success is an agent you have not tested.

⚠️

Test the denial. This is the step teams skip. A role that grants too much looks identical to a correct one until the day it does not. Five minutes spent confirming the agent cannot do the dangerous thing is the difference between a control and an assumption.

Patterns that work

Pattern	Shape	Why
One agent, one job	A narrow role per task, each with its own key.	The audit log tells you which job misbehaved. A single do-everything key tells you nothing.
Read first, write later	Ship the agent read-only. Add write tools once you trust it.	Most value is in the reading. Most risk is in the writing. They do not have to arrive together.
People on OAuth, machines on keys	Humans connect with OAuth; unattended jobs use API keys.	Puts real names in the audit log wherever a real person was actually responsible.
Name roles after work	`Supplier compliance`, not `Agent 2`.	Six months on, someone has to decide whether a role is still needed. The name is the only clue.

Patterns that go wrong

One key for everything. Convenient for a week. Then something leaks and you have no way to revoke narrowly and no way to tell which integration was at fault.
Full access "just to get it working". Temporary permissions are permanent permissions. Start narrow and widen against real denials in the log.
Granting a connector instead of its tools. There is no such grant, and the reason is that it would hand out payment initiation alongside reporting.
Keys in source control. Give each deployment its own key, keep them in your secret store, rotate on a schedule.

Running several agents at once

Many agents can share one tenant. Each gets its own credential, its own role and its own line in the audit trail, so "which agent did this" is always answerable. They share the tenant's daily call quota, which is worth knowing before you point five of them at the same plan. See limits and plans.

Roles & permissions

The four built-in roles, custom roles, tool allowlists and what each role can see in the console.

Teams & seats

Inviting people, assigning roles to seats, and what happens when someone leaves.

Governance & audit

Reading the log, spotting a role that is too tight or too loose, and proving what happened.