> ## Documentation Index
> Fetch the complete documentation index at: https://docs.everabyte.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

> Connect an AI client to the Everabyte MCP endpoint, including authentication, required scopes, and the tool surface.

Everabyte exposes an MCP server over Streamable HTTP. It lets MCP-capable clients read storage state, inspect organization context, and, for some tools, perform governance actions.

> [!WARNING]
>
> MCP requires a **paid subscription** and the `mcp` scope. Trial accounts are refused before the handshake with `403 MCP_TRIAL_LOCKED`.

## Endpoint

```text theme={null}
POST   https://api.everabyte.io/api/mcp
GET    https://api.everabyte.io/api/mcp
DELETE https://api.everabyte.io/api/mcp
```

The endpoint is not part of the REST reference because it speaks MCP, not the JSON envelope convention.

## Authentication

MCP uses a Bearer token containing the API key pair:

```text theme={null}
Authorization: Bearer base64(publicKey:secretKey)
```

Both of these are accepted:

| Form | Example |
| - | - |
| Base64 of `pk:sk` | `Bearer cGtfeW91cl9rZXk6c2tfeW91cl9zZWNyZXQ=` |
| Raw `pk:sk` | `Bearer pk_your_public_key:sk_your_secret_key` |

> [!WARNING]
>
> Base64 is an encoding, not encryption. Treat the token as a secret and send it only over HTTPS.

The endpoint reuses the same key validation as the REST API, so all the usual states apply: revoked, expired, company-only, surface, and trial checks.

## Requirements

| Requirement | Detail |
| - | - |
| Key scope | Must include `mcp` |
| Subscription | Must be paid; trials refused |
| Account type | Company workspace for storage tools |
| Transport | HTTPS only |

Failure codes:

| Code | Meaning |
| - | - |
| `MCP_SCOPE_REQUIRED` | The key lacks the `mcp` scope |
| `MCP_TRIAL_LOCKED` | The account is on trial |
| `401` | Missing or invalid Bearer credential |

## Tool surface

Tools are grouped by domain. Access to each tool is gated by capability, and every call is audited.

### Identity

| Tool | Purpose |
| - | - |
| `whoami` | Returns the authenticated caller, company scope, and resolved capabilities |

Use `whoami` first when debugging a connection. It confirms which key and scope the server resolved.

### Storage (read-only)

| Tool | Purpose |
| - | - |
| `list-buckets` | List buckets visible to the caller |
| `get-storage-status` | Capacity, used and remaining bytes, and the per-file upload limit |
| `list-folders` | List folders for a bucket, paginated |
| `list-files` | List files for a bucket, paginated |

These are read-only. MCP does not expose upload, delete, or move tools for storage in this documented surface.

### Organization and security

| Tool | Purpose |
| - | - |
| `get-business-dashboard` | Business summary |
| `list-team-members` | Team roster |
| `get-security-overview` | Security posture summary |
| `list-devices` | Enrolled devices |

### Audit

| Tool | Purpose |
| - | - |
| `list-activity` | Recent activity |
| `list-audit-logs` | Audit log entries |

### Sharing

| Tool | Purpose |
| - | - |
| `list-shares` | List shares |
| `revoke-share` | Revoke a share |

### Billing

| Tool | Purpose |
| - | - |
| `get-subscription-status` | Subscription state |
| `list-invoices` | Invoices |

### Governance

| Tool | Purpose |
| - | - |
| `disable-team-member` | Disable a team member |
| `lock-device` | Lock a device |

> [!TIP]
>
> Governance tools change state. Give them their own key with a narrow scope set, and review audit entries after use.

## Capability gating

Each tool declares the capabilities it requires. If the resolved permissions do not include them, the call returns a soft error listing the required capabilities rather than crashing the session.

```json theme={null}
{
  "error": "Insufficient capabilities",
  "required": ["file:read"]
}
```

This is returned as a tool result with `isError: true`, not an HTTP error.

## Minimal connection flow

1. Create a key in the dashboard with the `mcp` scope.
2. Restrict it to the buckets the client should see.
3. Base64-encode `pk:sk`.
4. Configure your MCP client with that Bearer token.
5. Call `whoami` to verify the resolved identity.
6. Call `list-buckets` to confirm reachable scope.

## Example

```bash theme={null}
CREDENTIALS=$(printf '%s:%s' "$EVB_PUBLIC_KEY" "$EVB_SECRET_KEY" | base64 -w 0)

curl -sS "https://api.everabyte.io/api/mcp" \
  -H "Authorization: Bearer $CREDENTIALS" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'
```

The exact client configuration depends on your MCP client. Everabyte documents the endpoint and credentials, not a specific client setup.

## Audit

MCP authorization failures and tool calls are audited, including scope denials and trial blocks. If you see unexpected denials, check the audit trail before assuming a client bug.

## Troubleshooting

| Symptom | Cause |
| - | - |
| `401` immediately | Missing Bearer, malformed encoding, revoked or expired key |
| `403 MCP_SCOPE_REQUIRED` | Key lacks `mcp` |
| `403 MCP_TRIAL_LOCKED` | Trial account |
| Tool returns "Insufficient capabilities" | Key's resolved permissions miss a required capability |
| Tools list is smaller than expected | Capability filtering by key scope |

## Related

> **[Scopes](https://docs.everabyte.com/authentication/scopes-and-permissions.md)**
>
> Adding the `mcp` scope.

> **[Access control](https://docs.everabyte.com/security/access-control.md)**
>
> Layered authorization.

> **[Compliance](https://docs.everabyte.com/security/compliance.md)**
>
> Audit and evidence.

> **[Integration overview](https://docs.everabyte.com/integrations/overview.md)**
>
> Other paths.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.