Agent integrations

Power301 MCP integration

Point any MCP-compatible client at one Power301 endpoint, sign in, and choose what the agent may do. It then discovers redirect-management tools and runs them behind your client’s approval flow.

MCP endpoint: POST https://mcp.power301.com/mcp/v1
Protocol: JSON-RPC 2.0 over HTTP
Sign-in: OAuth 2.1 (PKCE, dynamic client registration)
Or: Authorization: Bearer <API token>
Connected assistants: https://app.power301.com/mcp
REST source: https://api.power301.com/v1

5-minute setup

Most assistants need only the endpoint: they sign you in to Power301 and receive their own token, so there is nothing to copy. Scripts and clients that cannot sign in use an API token instead.

Add the server. Configure https://mcp.power301.com/mcp/v1 as a remote HTTP MCP server in your client (Claude: a custom connector; ChatGPT: a custom connector; Cursor or Codex: see below).
Sign in and choose. The client opens Power301: sign in, pick the workspace the assistant works in, choose the permissions it gets, and select Allow access. Each connection works in one workspace.
Check it. The client should list Power301 with its tools, and the assistant appears under AI assistants in your account, where you can disconnect it at any time.
No sign-in in your client? Create an API token from the account tokens page, keep it in POWER301_MCP_TOKEN (never in source control, prompts or logs), and send it as Authorization: Bearer. The checks below use one.

# Service discovery — no token required, returns no workspace data
curl -s "https://mcp.power301.com/mcp/v1"

Grant what the assistant needs. A signed-in assistant only sees the tools it was granted, and only in the workspace you picked. An API token has every tool in the workspace that issued it: keep it local to a trusted client or server-side process, use a separate token per client and environment so revocation stays isolated, and follow the REST Authentication guide for the rest of the token rules.

Permissions

The consent screen asks which of these the assistant may use. What you can grant depends on your role in the workspace; to change a grant later, disconnect the assistant and connect it again.

links:read

See your links, domains and click statsEvery read tool: links, QR codes, domains and their DNS, the workspace, members, the account, stats and access logs. Always granted.

links:write

Create and edit linksBranded links, QR codes and redirects; updates, bulk updates and imports. On by default; editor role and up.

links:delete

Delete linksSingle and bulk deletes. Editor role and up.

domains:write

Add and change domainsConnect, update and re-check domains. Editor role and up.

workspace:admin

Manage members and workspace settingsInvite, remove and change members, and update workspace and account settings. Manager role and owner.

Endpoint and authentication

GET https://mcp.power301.com/mcp/v1 returns unauthenticated service discovery — server name, version, the advertised endpoints, and a quick-start block. POST to the same URL is the JSON-RPC endpoint: every call is a JSON-RPC 2.0 envelope with jsonrpc, id, method, and optional params, and it requires the Authorization header.

Sign-in follows the MCP authorization spec. A POST without a token answers 401 with a WWW-Authenticate header pointing at the protected resource metadata, which names https://app.power301.com as the authorization server. Its /.well-known/oauth-authorization-server metadata advertises dynamic client registration (/oauth/register) and the authorization code flow with PKCE (S256). Access tokens last an hour; refresh tokens 30 days, and they rotate on use.

Two paths reach the same tools. The cURL checks above are the direct shortcut: one authenticated tools/list or resources/read POST answers 200 on its own, which is what makes them a good first check. A client instead runs the full MCP lifecycle — initialize, which returns the server capabilities and a session id, then a notifications/initialized acknowledgement, then tools/list and the tool calls. Your client library handles that for you; it matters when you read MCP logs, because a failure at initialize looks nothing like a failure at tools/list.

200

Discovery is reachableGET /mcp/v1 returns service metadata and the quick-start commands. It exposes no workspace data, so it is a safe first reachability check from any network.

401

JSON-RPC without a valid tokenPOST /mcp/v1 with no bearer token returns {"message":"Unauthenticated."} and the WWW-Authenticate header an OAuth client follows to sign you in. Use this to prove the client is reaching Power301 even before a token works.

202

Notification acceptednotifications/initialized returns 202 with no body. JSON-RPC notifications carry no id and get no result — an empty response there is success, not a dropped request.

Client setup

The blocks below are the canonical Power301 server information written in the shape many clients use: the endpoint alone for a client that signs in, or the endpoint plus a bearer header for an API token. Treat them as a pattern, not a schema: field names, environment-variable syntax, and credential storage belong to each client.

{
  "mcpServers": {
    "power301": {
      "url": "https://mcp.power301.com/mcp/v1"
    }
  }
}

Claude

In Claude, open Settings → Connectors → Add custom connector (open it directly), name it Power301 and paste https://mcp.power301.com/mcp/v1. Claude reads the sign-in metadata, opens Power301 to sign in, and comes back connected; then enable the connector in a conversation. No token or header is needed. See the remote MCP connector docs for the current flow.

ChatGPT

In ChatGPT, open Settings → Apps & Connectors (open it directly) and add a custom connector with https://mcp.power301.com/mcp/v1, choosing OAuth as the authentication. ChatGPT registers itself and sends you to Power301 to sign in.

Cursor

Cursor reads MCP config from project .cursor/mcp.json or global ~/.cursor/mcp.json and supports remote servers by url. Install Power301 in Cursor in one click, or add it by hand. With the URL alone, Cursor shows a login button for the server that runs the Power301 sign-in. With an API token, it expands environment variables inside headers using ${env:NAME}. See the Cursor MCP docs for the current UI and enterprise policy controls.

{
  "mcpServers": {
    "power301": {
      "url": "https://mcp.power301.com/mcp/v1"
    }
  }
}

VS Code

Install Power301 in VS Code in one click, or run MCP: Add Server from the command palette, choose HTTP and paste https://mcp.power301.com/mcp/v1. VS Code signs you in when the server first asks for it.

Codex CLI

Codex reads ~/.codex/config.toml, or a trusted project-scoped .codex/config.toml. Add the server by URL and run codex mcp login to sign in; with an API token instead, bearer_token_env_var keeps the token in the environment rather than the file. Keeping default_tools_approval_mode at prompt leaves every tool call behind an approval. See the Codex MCP docs.

codex mcp add power301 --url https://mcp.power301.com/mcp/v1
codex mcp login power301

Any other MCP client

For any other host, register Power301 as a remote HTTP (Streamable HTTP) server at https://mcp.power301.com/mcp/v1. A host that implements MCP authorization signs you in on its own; otherwise send Authorization: Bearer <API token> with each JSON-RPC request. Field names below are illustrative — check your host’s schema and the official MCP remote-server docs. Custom clients should initialize, discover capabilities, then call tools; the MCP server guide covers tools, resources, prompts, and approval expectations.

{
  "name": "power301",
  "transport": "streamable-http",
  "url": "https://mcp.power301.com/mcp/v1"
}

Verify the connection

Confirm the client lists Power301 as a connected server, then confirm it lists tools. A server that connects but shows no tools is usually an authorization problem, not a config problem.
Run the tools/list cURL check to split the two: if cURL returns tools and the client does not, the fault is on the client side — reload it and read its MCP logs.
Make the first authenticated call a read. resources/read on account://me confirms which account the connection acts as; with a signed-in assistant, ask it for the current workspace to confirm the one you picked.
Ask the agent to state the read or write it intends before it calls anything, and check the arguments in the approval dialog against that statement.

Capabilities and limits

The tool surface is discovered from the server at connection time, so this page documents the connection rather than a catalog that would drift. tools/list and resources/list on your own authenticated connection are the authority on what the agent can reach.

POST /mcp/v1 is the JSON-RPC endpoint and requires a bearer token, from sign-in or an API token; GET on the same URL returns discovery metadata unauthenticated.
A signed-in assistant lists only the tools its permissions cover and always acts in the workspace picked at sign-in, whatever workspace header it sends. Calling a tool outside the grant returns an error naming the permission it needs.
An authenticated client discovers both tools and resources on connect. Read the names, descriptions, and input schemas from that live list — in the client’s server view or in the Inspector with the token set — before you let an agent act on them.
resources/read with the account://me URI is the account-context read, and the cheapest way to confirm which workspace a token resolves to.
Tools carry MCP annotations: delete operations are hinted as destructive, and some analytics reads are hinted read-only. Use the hints to decide what stays behind an approval prompt, but read a missing hint as unknown rather than safe.

Discovery is the contract, not this page. Tool names, argument schemas, response shapes and the permissions behind each tool belong to the server version you are connected to. Read them from tools/list and resources/list, or from the server repository, and treat a change in the discovered surface as a breaking change until you have re-checked. Whatever the annotations say, your client’s approval flow is the boundary that stops an unwanted write.

A safe operating workflow

Redirects are production routing. The same loop works for a one-off edit and for a bulk migration, and it is worth following even when the agent sounds confident.

Discover. List tools and read their input schemas so you know what the agent can reach.
Inspect. Read the current state of the redirects in scope before proposing a change.
Preview. Ask for the affected set and the exact before/after values, with nothing applied.
Approve. Check the count and the target hosts against your intent in the client approval dialog. Keep destructive tools behind a prompt rather than an allowlist.
Execute. Apply the previewed set only, one call at a time for anything bulk, so a wrong argument stops at one record.
Verify. Re-read the changed redirects and confirm the new state. Rollback is your own workspace exports and the REST API — the MCP server does not promise one.

Prompt examples

These describe intent and leave tool selection to the client and server, which keeps them working as the tool surface changes. Start read-only, then move up the list.

Using the Power301 MCP server, list the redirects in my workspace with
their source hosts, destinations, and status. This is a read-only
inventory — do not create, update, or delete anything.

Troubleshooting

Config

The client will not load the serverValidate the file first — commas, quotes, and the top-level key. Clients disagree here: mcpServers in JSON, [mcp_servers.<name>] in Codex TOML, UI fields in Claude. A pattern copied from another client is the usual cause.

Env

The token is not being expandedConfirm the variable is exported in the process that launches the client, not just in your interactive shell. Cursor expands ${env:NAME} inside headers; Codex reads the variable named by bearer_token_env_var.

401

UnauthenticatedThe server was reached but no valid bearer token arrived. A signed-in client should start sign-in again; one that does not was disconnected or never supports OAuth, so reconnect it or use an API token. With an API token, check the header spelling, the token value, env expansion, revocation, and whether the client forwards custom headers at all.

403

Authenticated but refusedThe request was understood and rejected. For a signed-in assistant, the person who connected it may no longer belong to the workspace: connect it again. Otherwise re-check which account issued the token and what that account can reach, and confirm with the workspace owner rather than guessing.

-32602

A tool needs another permissionThe assistant called a tool its connection was not granted; the error names the permission. Disconnect it under AI assistants and connect it again with that permission, if your role allows it.

Tools

Connected, but no tools appearRun the tools/list cURL check. Tools in cURL but not in the client is a client discovery problem — reload or restart the client after any config change and read its MCP logs.

Network

Cannot reach the serverConfirm the machine can reach GET https://mcp.power301.com/mcp/v1 at all, that outbound HTTPS is allowed through any proxy, and that TLS interception is not breaking the connection.

REST API and next steps

MCP and the REST API are two doors into the same workspace. Use MCP when an agent should discover and operate tools conversationally; use REST when you need an exact, versioned contract — request fields, response bodies, error payloads, filtering, pagination, and rate-limit headers. Where MCP coverage stops, REST is the fallback rather than a workaround.

Authentication — token handling, rotation, and header rules for the REST API.
API reference — the exact REST operations behind redirect management.
Filtering & sorting — the read workflows worth doing over REST.
Official MCP documentation — the protocol, capabilities, and client expectations.
Power301 MCP product page — positioning and install entry points.