Connecting an agent
Every ScaiGit instance serves its agent interface over the Model Context Protocol (MCP) at:
1 | |
It speaks JSON-RPC 2.0 over HTTP POST, MCP protocol version 2025-06-18,
and needs a ScaiKey access token in the Authorization: Bearer header. What
the agent may do is decided by the token: whose it is, and which agent acts.
See Agents and risk tiers for the rules.
Getting a token#
ScaiGit accepts ScaiKey access tokens issued for ScaiGit's application (the token's audience is ScaiGit's client ID; your administrator can give it to you).
- An agent acting for a person — the usual case. The agent's own ScaiKey
application exchanges the person's token for a ScaiGit token with OAuth
2.0 Token Exchange (RFC 8693), at ScaiKey's platform token endpoint, with
audienceset to ScaiGit's client ID. The resulting token names the person as subject and the agent as actor; ScaiGit applies the person's rights and records both. - A service agent acting on its own. Your administrator maps the agent's ScaiKey application to a role in the instance's policy. It then gets that role's rights, and its consequential actions wait for a person's approval.
Configure your MCP client#
Most MCP clients take a URL and headers. For example:
1 2 3 4 5 6 7 8 9 | |
Keep the token in an environment variable or your client's secret store, not in the file itself.
Try it with curl#
1 2 3 4 | |
tools/list returns the tools available to this token. Administrative tools
stay hidden unless the caller's role grants them. Then call one:
1 2 3 4 5 | |
Errors#
Tool errors carry a stable code in error.data.code, such as
policy_denied, hitl_denied, hitl_timeout, not_found, conflict or
auth_expired. The tool reference
lists them all.
Calls that wait for approval#
A call that needs a person's approval stays open until someone decides it
in the console, for up to 30 minutes, and then returns the tool's result or
hitl_denied / hitl_timeout. Give your client's HTTP timeout room for that.
Every tool that changes something (T1 and up) accepts an optional
idempotency_key argument. Repeating a call with the same key and the same
arguments within 24 hours returns the original result instead of doing the
work again, and does not ask for approval twice.