# Vigilbase MCP server

> Connect an AI assistant to mcp.vigilbase.com to run security checks and to search and call the actions you can take in Vigilbase One.

Source: https://docs.vigilbase.com/one/mcp

The Vigilbase MCP server is one endpoint for AI assistants, such as Claude or another MCP client. Without signing in, an assistant can run the public [security tools](https://docs.vigilbase.com/tools/developers/mcp-server). After you sign in, it can also read your Vigilbase One workspace and take the same actions you can take in the dashboard, as you, inside one organisation, with your permissions.

- **Endpoint:** `https://mcp.vigilbase.com`
- **Protocol:** MCP `2026-07-28` over stateless Streamable HTTP. Clients on `2025-06-18` or `2025-11-25` connect with the `initialize` handshake, without a session.
- **Sign-in:** OAuth through Vigilbase Identity (`https://auth.vigilbase.com`), with PKCE, the first time the assistant uses a Vigilbase One tool.

Connections made to the earlier endpoint, `https://mcp.vigilbase.com/mcp`, keep working there. `https://mcp.vigilbase.com/tools` serves only the public security tools and never asks you to sign in.

## Connect a client

:::steps
1. **Add the endpoint to your client.** Use `https://mcp.vigilbase.com` as a remote MCP server. The security tools work straight away.
2. **Use a Vigilbase One tool.** The first time the assistant calls `search`, `execute` or another Vigilbase One tool, the server asks your client to sign in. Your client finds the sign-in server from `https://mcp.vigilbase.com/.well-known/oauth-protected-resource` and opens Vigilbase Identity. Some clients sign in as soon as you add the server instead.
3. **Choose an organisation and approve.** The access you approve applies to the one organisation you pick. The consent screen lists what the client asked for: read access to your workspace to start with. Only approve applications you recognise.
:::

The connection then appears under [Authorized applications](https://docs.vigilbase.com/one/getting-started/authorized-applications).

## Scopes

| Scope | Consent screen | What it allows |
|---|---|---|
| `mcp:connect` | Connect through MCP | Required for every connection. |
| `services:read` | Read services | The read-only service, customer and Cloudflare summary tools. |
| `billing:read` | Read billing information | The read-only billing, contract and quote summary tools. |
| `support:read` | Read support information | The read-only support tools. |
| `one:read` | Read your Vigilbase One workspace | The `search` and `execute` tools. `execute` sends `GET` and `HEAD` requests only. |
| `one:write` | Make changes in your Vigilbase One workspace | The `execute_write` (`POST`, `PUT`, `PATCH`) and `execute_delete` (`DELETE`) tools, which change data. |

The first sign-in asks for `mcp:connect` and `one:read`. When the assistant first calls `execute_write` or `execute_delete`, the server answers with an `insufficient_scope` challenge for `one:write`, and your client asks you to approve changes. If the first tool the assistant uses is a write tool, the sign-in asks for both at once. `one:read` and `one:write` are separate: a client that should read and change your workspace holds both. Neither one grants the other or any of the summary-tool scopes. Every request is still checked against your current role and permissions in the organisation, so a scope never gives a client more access than you have.

## Code mode: search and execute

With `one:read` or `one:write`, the server adds four tools that cover the dashboard's [API](https://docs.vigilbase.com/one/api/reference). Reading and changing data are separate tools, so your client can let reads run freely and ask you before every change. Instead of one tool per action, the assistant writes a short JavaScript function and the server runs it in an isolated sandbox with no network access.

### search

`search` runs a function with `spec` in scope: an OpenAPI 3.1 description of the operations you can use. Operations that only Vigilbase staff can use are listed only for staff, and writes only for `one:write`.

```js filename=search.js
// Find Cloudflare operations
async () =>
  Object.entries(spec.paths).flatMap(([path, item]) =>
    Object.entries(item)
      .filter(([, op]) => /cloudflare/i.test(path + op.summary))
      .map(([method, op]) => ({ method: method.toUpperCase(), path, summary: op.summary })))
```

```js filename=search-operation.js
// Read one operation's parameters and request body
async () => spec.paths['/one/v1/change-requests']?.post
```

`spec` lists each v1 operation once, at its `/one/v1/…` path, and every operation not in v1 yet at its `/api/…` path. The same operations, with their fields, are in the [API reference](https://docs.vigilbase.com/one/api/reference), and the v1 operations are in the OpenAPI document at `https://api.vigilbase.com/one/v1/openapi.json`.

### execute, execute_write and execute_delete

| Tool | Methods it can send | Needs |
|---|---|---|
| `execute` | `GET`, `HEAD` | `one:read` |
| `execute_write` | `POST`, `PUT`, `PATCH` | `one:write` |
| `execute_delete` | `DELETE` | `one:write` |

Each runs a function that can call `one.request({ method, path, query, body })`, with only its own methods; a request with another method fails and names the tool to use instead. The server makes each request to Vigilbase One on your behalf and returns `{ status, ok, contentType, body }`. Your access token never enters the sandbox.

```js filename=execute.js
async () => {
  const account = await one.request({ method: 'GET', path: '/api/account' })
  return account.ok ? account.body : { status: account.status, error: account.body }
}
```

Fill in path parameters yourself, for example `/one/v1/customers/<id>/services`. Put query parameters in `query`, not in the path.

Some writes, such as submitting a change request, need an `idempotencyKey`: pass a new UUID, for example `crypto.randomUUID()`, for each action, and reuse it only to retry that same action. It is sent as the `Idempotency-Key` header. You cannot set any other header.

> [!WARNING]
> `execute_write` and `execute_delete` change real data, with your permissions. Assistants should confirm with you before they change anything.

## What MCP cannot do

- **Actions that need a fresh sign-in.** Anything the dashboard protects with a step-up prompt, such as changing billing, payment methods or organisation security, is refused through MCP. Do it in [Vigilbase One](https://one.vigilbase.com).
- **File uploads.** Operations that take a file (`multipart/form-data`), such as support attachments or a partner logo, are not available through MCP.
- **Account credentials.** Sign-in methods, sessions and developer API keys are managed in Vigilbase Identity, not through MCP.
- **Other organisations.** A connection is bound to the organisation you chose when you approved it.

## Limits

| Limit | Value |
|---|---|
| Requests to the MCP endpoint | 120 per minute per access token, or per client IP without signing in |
| Vigilbase One API calls through the execute tools | 120 per minute per user |
| Calls per run | 20 |
| Response size per call | 1 MiB |
| Time per run | 30 seconds |
| Program size | 32 KiB |

A run that goes over a limit returns an error to the assistant. Results longer than 100,000 characters are cut off; ask for less data.

## Revoke access

Open [Authorized applications](https://one.vigilbase.com/settings/authorized-applications), click **Revoke** on the client's entry and confirm with **Revoke access**. Its access stops straight away. See [Authorized applications](https://docs.vigilbase.com/one/getting-started/authorized-applications#revoke-access).

Every request a client makes through the execute tools is recorded in the audit log with its method and route.