Platform
ScaiWave ScaiGrid ScaiCore ScaiBot ScaiDrive ScaiKey Models Tools & Services
Solutions
Organisations Developers Internet Service Providers Managed Service Providers AI-in-a-Box
Resources
Support Documentation Blog Downloads
Company
About Research Careers Investment Opportunities Contact
Log in

Connecting an agent

Every ScaiGit instance serves its agent interface over the Model Context Protocol (MCP) at:

text
1
https://<organisation>.scaigit.scailabs.ai/api/scaigit/mcp

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 audience set 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:

json
1
2
3
4
5
6
7
8
9
{
  "mcpServers": {
    "scaigit": {
      "type": "http",
      "url": "https://<organisation>.scaigit.scailabs.ai/api/scaigit/mcp",
      "headers": { "Authorization": "Bearer ${SCAIGIT_TOKEN}" }
    }
  }
}

Keep the token in an environment variable or your client's secret store, not in the file itself.

Try it with curl#

bash
1
2
3
4
curl -s https://<organisation>.scaigit.scailabs.ai/api/scaigit/mcp \
  -H "Authorization: Bearer $SCAIGIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

tools/list returns the tools available to this token. Administrative tools stay hidden unless the caller's role grants them. Then call one:

bash
1
2
3
4
5
curl -s https://<organisation>.scaigit.scailabs.ai/api/scaigit/mcp \
  -H "Authorization: Bearer $SCAIGIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"scaigit_repo_list","arguments":{}}}'

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.

Updated 2026-10-24 21:16:39 View source (.md) rev 1