MCP: connect and authenticate

The server

Inkwave's MCP server is at https://mcp.inkwave.space. It has two addresses:

The publication id must be a lowercase UUID, exactly as Inkwave shows it in the connection address. Any other value is answered with 404 before your credential is even read.

On a /p/<publication-id>/mcp address the publication is checked against your credential. An API key issued for another publication is refused, and so is a sign-in that wasn't approved for this one. The address can only narrow what a credential reaches, never widen it.

Transport: MCP's Streamable HTTP transport, stateless. There are no sessions: every request carries its own credential and stands alone. Responses are JSON, not an event stream. A GET /health probe answers without authentication.

The full list of tools, with their parameters and results, is in MCP tools. What each permission allows is in MCP scopes.

These Developers pages are reference for docs.inkwave.space only. They don't open in the help panel inside the Inkwave app. For the step-by-step version in the app, see the AI assistants guide.

Authenticating

Every request sends a credential as Authorization: Bearer <credential>. There are two kinds.

Signing in (OAuth)

For assistants that can add a connector by its address, such as Claude.

1. Add https://mcp.inkwave.space/mcp, or one publication's address, as a connector. Nothing else needs configuring.

2. Your assistant's first request has no credential, so the server answers 401 with a challenge pointing at its metadata:

   WWW-Authenticate: Bearer realm="inkwave", resource_metadata="https://mcp.inkwave.space/.well-known/oauth-protected-resource"
   

   For a /p/<publication-id>/mcp address, the metadata URL ends /.well-known/oauth-protected-resource/p/<publication-id>/mcp instead.

3. The assistant fetches that document (OAuth protected resource metadata, RFC 9728). It names the resource, the authorization server to sign in with, and scopes_supported: profile, email and offline_access. Tokens are accepted in the Authorization header only, never in a query string.

4. You sign in to Inkwave, then Inkwave's own consent page asks which publications the assistant may use and what it may do in each. Those choices are the connection's scopes. The sign-in itself grants nothing: the OAuth scopes above only say who you are.

5. The assistant gets an access token beginning oat_ and sends it on every request.

What a signed-in connection may do is capped by your role in each publication, checked on every request. If your role changes, the connection narrows with it at once. You can see and disconnect your connections from your account menu, Connected Assistants.

API keys

For tools where you paste a credential into a config file, such as Claude Code, Cursor or VS Code.

1. The owner or an admin opens Settings, MCP, clicks Create Key, names it and ticks what it may do.
2. The key, beginning inkw_mcp_, is shown once. Inkwave keeps only a hash, so copy it then.
3. Configure your client with the publication's server URL from that page and send Authorization: Bearer inkw_mcp_….

A key belongs to one publication, chosen when it is created. A key's permissions can be changed later with Manage permissions, without re-issuing it, and take effect on its next request. Revoking a key is permanent. A key has exactly what was ticked, except that a key created before 16 October 2026 whose permissions have not been saved since also keeps the audience, subscriber and post-performance reads it always had; see MCP scopes.

When a credential is refused

• No credential, or one that is not shaped like an Inkwave credential: 401 with the challenge above. The second case adds error="invalid_token".
• A well-formed credential that is revoked, expired, disconnected or unknown gets no HTTP error. Listing tools still works, because that never reaches a publication, but every tool call returns an error result, such as "This key was refused. It may have been revoked, expired, or never existed." The message is the same whichever of those it was.

Choosing a publication

On a key, or on any /p/<publication-id>/mcp address, the publication is fixed by the connection, and tools take no publication argument.

A sign-in at the bare /mcp may reach several publications, so two things change there:

• list_my_publications is offered. It lists each publication the connection reaches, with its id, its name, your role there and the scopes the connection holds in it. A publication whose plan lacks API access is left out.
• Every other tool takes publication_id, the id of the publication the call acts in. Always pass it. A call without it, on a connection that reaches more than one publication, is refused as ambiguous. Each result names the publication it acted in.

confirm_publication

Actions that can't be undone also take confirm_publication: the publication's exact name, as list_my_publications shows it. It is required only when the connection reaches several publications and the call chose one with publication_id. On a key or a /p/<publication-id>/mcp address it is never needed.

A missing or wrong name refuses the call, and nothing is done. The refusal never says what the right name is. If two publications the connection reaches share a name, the name can't tell them apart, so the call is refused too: rename one, or use that publication's own address.

Errors

A tool that fails returns a normal MCP result with isError: true and a sentence saying what happened, rather than a protocol error. The sentence is written for the assistant to act on, for example:

• A missing scope: This connection was not granted the "posts:write" permission. Reconnect the application and allow it, or issue a key that includes it.
• A plan without API access (FEATURE_NOT_IN_PLAN): This publication's plan doesn't include API access. Its keys and connections are kept and work again after an upgrade.
• A daily write limit (RATE_LIMITED): see Limits.
• Something you named that doesn't exist, such as a template or a segment: the error says what wasn't found.
• A conflict, such as a website page that changed since you read it: the error says what to do next.
• A failure inside Inkwave: the error names the operation and says not to assume nothing was written. Check the current state before retrying a write.

Tools reject arguments they don't define, and values outside the documented range, before anything is sent.

Limits

Three limits apply:

Only changes count towards the daily limits, not reads. A change is counted when it starts, so one that then fails still counts, and a loop retrying a failing write uses up the day's budget. A call refused because the plan lacks API access never counts. If your plan has a daily write limit, Settings, MCP shows it.