---
summary: Point an MCP client at your instance's /api/scaigit/mcp endpoint with a ScaiKey
  access token.
title: Connecting an agent
path: guides/agents
status: published
---

# Connecting an agent

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

```
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](/docs/scaigit/concepts/agents) 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
{
  "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
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
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](/docs/scaigit/reference/mcp-tools)
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.
