> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nasiko.com/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP gateway overview
> How agents get tool access: connectors, per-agent permissions, and the gateway endpoint.
Every deployed agent gets **one fixed URL** for every tool action, no matter how many tools or providers sit behind it: the **MCP gateway**. Adding, removing, sharing, or restricting a tool is a configuration change — the agent is never redeployed.
The gateway speaks the [Model Context Protocol](https://modelcontextprotocol.io). Agents call it with JSON-RPC `tools/list` and `tools/call`, and it fans each call out to whichever backend implements that tool.
Register a managed integration or your own running MCP server.
Upload source and let Nasiko build, harden, and run it.
Control which connectors and tools an agent may use.
Register connectors and set rules in the web app.
## Two kinds of provider, one interface
| Term | Meaning |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Toolkit** | A managed, pre-built integration (Gmail, Slack, GitHub, Google Calendar) — OAuth and credential refresh handled for you |
| **MCP server** | A server speaking MCP directly — one you run elsewhere and register by URL, or one you upload for Nasiko to build and deploy |
| **Connector** | The neutral term for a registry row representing either kind |
Everyone using a shared connector connects with **their own account**. Sharing never shares the underlying login.
## The delegation token
An agent is untrusted code serving many users, so its identity can't be baked in at deploy time. Nasiko uses a **delegation token**: a short-lived, scoped credential saying "I am this agent, acting for this user."
* When the platform proxies a user's request to an agent container, it mints a token (minutes, not hours) and injects it into the inbound request. The user's session credential is stripped before the request reaches the container — an agent never sees or replays a real login.
* The agent forwards that token to the gateway in the `x-nasiko-agent-token` header. It's the **only** credential `/api/mcp` accepts.
* The token is scoped to one purpose, expires quickly, and is rejected if signature, audience, or expiry don't check out.
Calling `/api/mcp` directly while testing requires a delegation token, not your login token. There's no way to authenticate to this endpoint with a session credential.
## The gateway endpoint
Agents call exactly one route, authenticated by delegation token:
| Method | Endpoint | Purpose |
| ------ | ---------- | ----------------------------------------------------------- |
| `POST` | `/api/mcp` | JSON-RPC — `initialize`, `ping`, `tools/list`, `tools/call` |
```json tools/list request theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list"
}
```
```json tools/list response theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"tools": [
{ "name": "GMAIL_SEND_EMAIL", "description": "Send an email via Gmail", "inputSchema": { "...": "..." } },
{ "name": "a1b2c3d4__search_docs", "description": "Search internal documentation", "inputSchema": { "...": "..." } }
]
}
}
```
```json tools/call request theme={null}
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "GMAIL_SEND_EMAIL",
"arguments": { "to": "user@example.com", "subject": "Hi", "body": "..." }
}
}
```
```json tools/call response theme={null}
{
"jsonrpc": "2.0",
"id": 2,
"result": { "status": "sent" }
}
```
Tool names from custom MCP server connectors are namespaced `{connector-id-prefix}__{tool_name}`, so two connectors can't collide. Managed toolkit tools keep their natural names (`GMAIL_SEND_EMAIL`, `SLACK_POST_MESSAGE`).
### Blocked and approval-required calls
A `tools/call` can return a JSON-RPC error instead of a result:
```json blocked theme={null}
{
"jsonrpc": "2.0",
"id": 2,
"error": { "code": -32000, "message": "Tool 'GMAIL_SEND_EMAIL' is blocked or disabled for this agent." }
}
```
```json approval required theme={null}
{
"jsonrpc": "2.0",
"id": 2,
"error": {
"code": -32001,
"message": "Tool 'GMAIL_SEND_EMAIL' requires user approval. Grant access in the agent settings.",
"data": { "server": "gmail" }
}
}
```
## Permissions
Every tool call resolves through two layers, in order:
1. **Reachability** — can the calling user reach this connector? (They own it, it's shared with them, or it's a globally available toolkit.)
2. **Per-agent permission** — is the connector enabled for this agent, and is this tool allowed, blocked, or gated behind approval?
Nothing needs configuring to grant an agent access to a connector its caller can already reach — access propagates the moment a connector is shared. Full model: [per-agent tool permissions](/onboarding/acl/user-agent-mcp).
## Management routes
Session-authenticated and access-controlled — everything the CLI and dashboard use:
| Method | Endpoint | Purpose |
| --------------- | ------------------------------------------------------ | -------------------------------------------------- |
| `GET` | `/api/mcp/catalog` | Browse connectable services |
| `POST` | `/api/mcp/connect` | Unified connect, any auth type |
| `GET` / `POST` | `/api/mcp/connectors` | List visible connectors / register a custom server |
| `POST` | `/api/mcp/connectors/probe` | Detect a server's auth type before registering |
| `GET` | `/api/mcp/connectors/my-uploads` | Your uploaded servers and build state |
| `GET` | `/api/mcp/connectors/{id}/grants` | List a connector's shares |
| `POST`/`DELETE` | `/api/mcp/connectors/{id}/grants/public` | Grant or revoke public access |
| `POST`/`DELETE` | `/api/mcp/connectors/{id}/grants/users/{user_id}` | Grant or revoke access for one user |
| `POST`/`DELETE` | `/api/mcp/connectors/{id}/grants/agents/{agent_id}` | Grant or revoke access for one agent |
| `POST` | `/api/mcp/connectors/upload` | Upload a zip — build and deploy |
| `POST` | `/api/mcp/connectors/upload-github` | Same, from a GitHub URL |
| `GET` | `/api/mcp/connectors/{id}/build-status`, `/build-logs` | Poll build progress |
| `GET`/`PUT` | `/api/mcp/agents/{agent_id}/tools` | View / bulk-update per-tool rules |
| `DELETE` | `/api/mcp/agents/{agent_id}/permissions` | Reset to full default-allow |
## Related
* [Artifact registry](/artifact-registry/overview) — MCP server packages as reusable artifacts
* [Access control overview](/onboarding/acl/overview)