AI agents (MCP)

Sencai runs a server that speaks the Model Context Protocol (MCP) - an open standard that lets an AI assistant call a defined set of tools on your behalf, with its own authentication and scoping, rather than you copy-pasting data back and forth. This page covers connecting an MCP-capable AI client (Claude, another MCP client, or your own agent) to your organization.

Endpoint and authentication

https://mcp.sencai.space/mcp

The server speaks MCP’s Streamable HTTP transport over this single URL (the same endpoint handles the protocol’s connection, tool-call, and teardown requests). Authenticate with a personal access token - Authorization: Bearer sencai_pat_... - not your browser session. There’s no separate account or API key system for MCP specifically: it’s the same token described on that page, and it reaches the same organization-scoped surface.

Setting it up

1. Create a token at Settings → Integrations → AI Agents (/gravity/settings/integrations/ai-agents) - see API tokens for the exact steps. Use read if you only want the AI assistant to look things up; use read/write if you also want it able to take the gated write actions below. To let it read your Admin Center contacts, switch on Restrict permissions and tick contacts:read (and handbook:read for the handbook).
2. In your MCP client, add a server pointing at https://mcp.sencai.space/mcp using the Streamable HTTP transport, and set an Authorization: Bearer <your token> header on it. Exactly where you enter the URL and header depends on your specific client - consult its own documentation for MCP server configuration.
3. If you want write actions available, an Owner or Admin also needs to turn on AI-agent write access for the organization from the same settings screen (see below) - a token alone isn’t enough.

The same settings screen shows an Agent Activity log of every write action an AI agent has taken through your organization’s tokens, so you can review what happened after the fact.

Read tools

Every read tool is automatically scoped to your own organization - none of them accepts an organization ID, and none can be pointed at anyone else’s data.

Tool	What it returns
get_organisation_info	Your organization’s name and account tier
get_billing_status	Current subscription tier and quota limits (max instances, members, monthly budget)
list_cloud_instances	Cloud instances owned by your organization
get_cloud_instance_status	Status of one instance, by ID
list_fleet_agents	Fleet agents enrolled under your organization
get_compliance_score	Your organization’s current compliance score
search_docs	Full-text search over Sencai’s public documentation
handbook_search	Search or list your organization’s Admin Center handbook pages (title, excerpt)
handbook_get_page	One handbook page with its full Markdown, returned raw as untrusted data
contacts_list	Your organization’s contact book, optionally filtered (personal data)
contacts_get	One contact card
responsibilities_list	The responsibilities matrix: who is primary and backup for which area
ping	Liveness/echo - no data access

The handbook tools need handbook:read on the key, and contacts_list, contacts_get and responsibilities_list need contacts:read. A key that lacks one gets permission_denied: <permission> from that tool and nothing else is returned. A default read token holds handbook:read but not contacts:read; to let an agent read contacts, issue the key with restricted permissions as described in API tokens.

Write tools

Write tools require two things to be true, checked server-side on every call:

1. The token used has the read_write scope.
2. AI-agent write access is turned on for the organization (off by default - an Owner or Admin turns it on from the same settings screen, on any plan including Free).

A write that would take the organization past the free configuration’s own limits (a sixth managed resource, or a second member) is handled the same way it is for a browser session - see Organization plans for what that limit is today.

Tool	What it does
create_cloud_instance_from_marketplace	Deploys a new cloud instance from an approved marketplace app’s template
invite_organisation_member	Invites an existing Sencai user (by email) into your organization
trigger_runbook	Triggers an existing runbook against your organization’s fleet

Guardrails on the write tools

• invite_organisation_member can only assign the Member or Viewer role - never Owner or Admin. Granting elevated access stays a human-only action through the normal invite flow in the app.
• invite_organisation_member only works for an email address that already has a Sencai account; it doesn’t send an invitation to someone who has never signed up.
• trigger_runbook requires an explicit confirm: true argument and refuses to call the backend at all without it. If the target runbook itself also requires human confirmation, triggering it still leaves the execution in a pending state needing a separate approval in the app - confirm: true on the tool call doesn’t skip that.

Write actions are being rolled out gradually, so a specific write action may not be available yet even with everything above turned on.

What’s next

• API tokens - create and manage the token this connects with
• Platform API overview
• Audit log - every write action an agent takes is recorded there too, in addition to the in-app Agent Activity log
• FAQ