# MCP connections
MCP (Model Context Protocol) is a way for an AI assistant to work with another service. With Approximated's MCP connection, you can ask your assistant to check a domain, look at traffic, or change a setting. You choose what it can access.
The app you use to talk to the assistant is called a **client**, such as Claude Code. It needs to support remote HTTP MCP connections. Choose **OAuth** to sign in and approve access in your browser, or a **token** to create a secret and paste it into your client's connection settings.
Server URL
`https://cloud.approximated.app/mcp`
Manage both kinds of connection on the [MCP tokens page](https://cloud.approximated.app/mcp-tokens) in your Approximated dashboard.
## Connect with OAuth
OAuth lets you connect by signing in to Approximated in your browser. Use this option if your client supports MCP with OAuth.
1. Add `https://cloud.approximated.app/mcp` in your client's MCP connection settings.
2. Follow the client's sign-in link. Sign in to Approximated and complete two-factor authentication if it is enabled.
3. Check the client name, then choose which clusters it can use.
4. Select the actions it can take and approve the connection. Nothing is selected by default.
5. Return to your assistant and ask it to check its access.
Example prompt
“Show me which Approximated clusters and permissions this connection can use.”
To stop the connection later, open [MCP tokens](https://cloud.approximated.app/mcp-tokens) and select **Revoke**.
### OAuth technical reference
Approximated supports OAuth client discovery, dynamic registration, authorization with PKCE S256, and rotating refresh tokens.
Access tokens last one hour. A compatible client refreshes them automatically. Revoking the connection invalidates both its access and refresh credentials.
The assistant can call `whoami` to confirm its effective clusters and permissions after connecting.
## Connect with a token
A personal token is a secret that lets your client use the access you select. Choose this option if you want to configure the connection yourself.
1. Open [MCP tokens](https://cloud.approximated.app/mcp-tokens) and choose **Create token**.
2. Name it so you can recognize it later, such as “Claude Code on my laptop”. Choose its clusters and permissions.
3. Choose **Create token**, then **Copy token** and save it securely. The full token is shown only once.
4. Paste the token into your client's authentication settings, using the server URL above. For Claude Code, choose **Copy command** in the dashboard and run it in your terminal.
Once you have saved it, choose **Done — hide token**. If you lose the token, create a replacement and revoke the old one.
### Token settings and Claude Code command
Customer MCP tokens start with `apxcmcp_`. Clients that accept HTTP headers need `Authorization: Bearer` followed by your token.
The dashboard's Claude Code command uses this format. Replace the example value with your token:
```bash
claude mcp add --transport http approximated https://cloud.approximated.app/mcp --header "Authorization: Bearer apxcmcp_YOUR_TOKEN"
```
You can have up to 25 active connections and tokens. Revoke an unused one if you reach that limit.
## Clusters and permissions
Choose **where** the assistant can work and **what** it can do. These are separate choices, and no action permissions are granted by default.
### Choose its clusters
**Selected clusters** limits the connection to the clusters you pick. **All clusters you can access** includes your current and future clusters while you have access to them.
Your own cluster membership is checked on every call. If your membership is removed, the connection loses access to that cluster, even if you selected it when you connected.
### Choose its actions
Start with the actions needed for your task. For example, **Clusters: View** lets the assistant read cluster details, addresses, regions, and configured capabilities. Traffic analytics and request logs each need their own View permission.
View, Create, Update, and Delete are separate grants. Allowing an assistant to create or change something does not also let it view that feature. Allowing View does not let it make changes.
The assistant can always check its own access, read documentation, and suggest a feature after connecting. Other tools are hidden from its tool list if their required permission is missing.
### Permission reference
In the dashboard, View is `read` and Run usually means `execute`. Running a request trace uses `trace_requests:create`. Cluster details require `clusters:read`.
| Task | Permission | Example tools |
| --- | --- | --- |
| Read cluster details | `clusters:read` | `get_cluster_info` |
| View traffic and latency | `analytics:read` | `traffic_series`, `traffic_top`, `latency_series`, `vhost_rollup` |
| Inspect request logs | `request_logs:read` | `request_logs` |
| View or manage domains and upstream pools | `virtual_hosts:read`, `create`, `update`, or `delete`, for the corresponding action | `get_vhost`, `create_vhost`, `list_vhost_upstreams`, `update_vhost_upstream` |
| View, validate, or change Edge Sequences | `edge_sequences:read` for reads and validation; `create`, `update`, or `delete` for changes | `validate_edge_sequence`, `update_edge_sequence_draft`, `promote_edge_sequence_draft`, `set_edge_sequence_active` |
| View or manage form protection | `edge_verify:read`, `create`, `update`, or `delete` | `list_edge_verify_rules`, `create_cluster_edge_verify_rule` |
| View or manage event notifications | `webhooks:read`, `create`, `update`, or `delete` | `list_webhooks`, `create_webhook` |
| Look up DNS or generate setup instructions | `dns_checks:execute` | `check_dns`, `check_caa`, `get_dns_instructions` |
| Issue a DNS Widget credential | `dns_widget:create` | `create_dns_widget_token` |
| Read traces or send a diagnostic request | `trace_requests:read` to inspect; `trace_requests:create` to send | `list_traces`, `get_trace`, `send_trace` |
| View or run regional monitoring | `regional_monitoring:read` to view; `regional_monitoring:execute` to run | `get_regional_monitor_checks`, `run_regional_monitor_check` |
| Run a fresh domain health check | `force_check:execute` | `force_vhost_check` |
`whoami`, documentation tools, and `suggest_mcp_feature` are always available to an authenticated connection.
To change a connection's access, authorize a new connection or create a replacement token with the permissions you need. Then revoke the old one.
## What agents can do
A **tool** is a function the assistant calls to read or change something in Approximated. You describe the task in plain language; the assistant chooses a tool and supplies its inputs. Its available tools depend on your permissions.
Start by asking it to check its access. Each tool tells the client which inputs it accepts. If two clusters share a name, use the cluster ID. If a domain appears on several clusters, give the cluster ID or virtual-host ID.
### Inspect domains and clusters
Ask which domains are configured, where their traffic goes, or which addresses and regions a cluster uses. This is a useful first step when investigating a setup.
Example prompt
“Show the configuration for app.example.com on my production cluster.”
#### Tools and inventory details
`whoami` reports the connection's effective access. `get_vhost` reads a domain's configuration, and `get_cluster_info` reads cluster details.
Cluster addresses and regions come from locally stored inventory at the last sync. Image capabilities describe the configured image.
### Understand traffic and errors
Ask for traffic trends, response times, or the domains with the most errors. Request logs can help you inspect individual requests when logs are available on the cluster.
Example prompt
“Which domains had the most errors on my production cluster in the last 24 hours?”
#### Analytics, log limits, and time windows
##### Traffic analytics
Tools include `traffic_series`, `traffic_top`, `latency_series`, and `vhost_rollup`.
- Default window: 24 hours. Maximum requested span: 720 hours (30 days).
- Series: at most 48 points. Top-value and virtual-host rollups: at most 50 items.
- ASN breakdowns require a window of 48 hours or less.
##### Request logs
The `request_logs` tool returns requested and effective bounds, plus retention metadata.
- Default window: one hour. At most 200 rows per page.
- The requested span is limited to 720 hours and further bounded by the cluster's log retention.
- Use `next_cursor` with identical absolute start/end bounds and filters for the next page.
##### Time windows
Supply either `hours` or paired `start`/`end` timestamps, never both. Absolute timestamps need explicit RFC3339 offsets, such as `2026-10-08T10:00:00Z`.
These limits bound queries. They do not guarantee that data exists for the whole requested period.
### Check DNS and help with setup
Ask whether a domain points to the right place, whether its certificate authority is allowed, or how to add its DNS records. The assistant can also issue a short-lived credential for the DNS Widget.
Example prompt
“Check the DNS records for app.example.com and explain what needs to change.”
#### DNS and widget tools
`check_dns` looks up DNS records. `check_caa` checks certificate-authority restrictions for a chosen cluster. `get_dns_instructions` generates setup instructions.
`create_dns_widget_token` requires the exact, unique name of an active API key on the chosen cluster and returns a short-lived widget token. See [DNS Widget](./dns-widget.md#dns-widget) for renewal and revocation behavior.
### Investigate a failing request
Ask the assistant to inspect a saved request trace or run a fresh diagnostic check. A trace sends a real request to your origin, so choose a method and path appropriate for your application.
Example prompt
“Send a GET request to /health on app.example.com and show me the trace.”
#### Trace and monitoring details
`send_trace` returns a trace ID while the request runs. Poll `get_trace` with that ID for completion.
- `list_traces` returns at most 50 records.
- Response bodies shown through MCP are capped at 10,000 bytes. Check `body_truncated`.
- `get_regional_monitor_checks` reads regional results; `run_regional_monitor_check` runs a fresh check.
- `force_vhost_check` runs a fresh domain health check.
- Regional and domain checks require an existing URL monitor.
Some diagnostics require enabled cluster features and compatible image capabilities.
### Change routing and integrations
With the matching permissions, an assistant can create or update domains, manage upstream origins, edit Edge Sequences or Edge Verify rules, and manage webhooks.
Example prompt
“Change app.example.com's target to origin.example.com on port 443.”
#### Configuration behavior
Upstream changes use the parent virtual host's permissions. Enable load balancing on that virtual host to serve its upstream pool.
Edge Sequence drafts, promotion, activation, ordering, and historical versions are separate operations. See [Edge Sequences](./edge-sequences.md#edge-sequences) for how they affect traffic.
The permission reference above lists example tools and the separate grants for each action.
### Look up documentation
The assistant can read Approximated documentation through the connection. It can also send a feature suggestion if a capability is missing.
#### Documentation tools and snapshot limits
`list_doc_sections` returns section IDs, source URLs, and the bundled snapshot's `generated_at` timestamp.
- `get_doc_section` accepts up to five IDs.
- `search_docs` needs at least two characters and returns up to ten matches.
- Follow the source URL to compare the snapshot with the public docs.
`suggest_mcp_feature` sends feature feedback.
### Rate limits and feature availability
The overall limit is 120 tool calls per minute per user, shared across that user's connections.
DNS, request-log queries, diagnostic requests, and monitoring also have their own limits. Request-log access and some diagnostics depend on the cluster's enabled features and image capabilities.
## Troubleshooting
### I cannot connect
Check that the server URL is `https://cloud.approximated.app/mcp` and your client supports remote HTTP MCP. OAuth also needs a client that supports its sign-in flow. For a token connection, check the token value and Bearer header in the token settings above.
### The connection says unauthorized or expired
Check whether it was revoked. An OAuth client may need to reconnect if it cannot refresh its credentials. If you lost a personal token, create a replacement.
### A tool is missing or permission is denied
Ask the assistant to check its access with `whoami`, then compare the result with the permission reference. Reconnect with the missing action selected.
### A cluster or domain is not accessible
Check the connection's cluster selection and your current membership. Use numeric IDs when cluster names or domain names are ambiguous.
### Logs or diagnostics are unavailable
Check the cluster's enabled features, image capabilities, log retention, and whether the virtual host has a URL monitor. Try a shorter window. If a rate limit is reported, wait before trying again.
### I want to stop a connection
Choose **Revoke** on the [MCP tokens page](https://cloud.approximated.app/mcp-tokens). New calls using that connection will fail.
Removing your cluster membership removes access to that cluster. It does not revoke the credential or remove access to other granted clusters.