Connecting a client

wondeya’s MCP server speaks Streamable HTTP at https://api.wondeya.com/mcp and authenticates with OAuth 2.1. You do not create or paste a credential: you point a client at the URL, it discovers that the endpoint needs OAuth, your browser opens to wondeya, and you approve a consent screen. Because the sign-in is a browser flow, browser assistants connect the same way coding agents do.

How connecting works

Every client follows the same three beats, most of it invisible:

Add the server by its URL

https://api.wondeya.com/mcp, as an HTTP (Streamable HTTP) server. No header, no token.

The client discovers the endpoint needs OAuth, registers itself, and opens wondeya in your browser. Sign in if you are not already.

Approve the consent screen

One screen names the client, the workspace the connection will be bound to, you, and the scopes it asks for. Approve it and the client is connected.The connection is bound to the workspace active in your session at that moment. To connect for a different workspace, switch workspace in the console first, then start the connection.

Grant the narrowest scopes that do the job. A connection with only landings:read and knowledge:read can audit a workspace and cannot change a thing. Your role caps what you can grant: an owner or admin can grant read and write; a member can grant read only. The MCP overview lists every scope and what it unlocks.

Browser assistants: Claude and ChatGPT

Add wondeya as a custom connector, using the same URL. In the assistant’s connector settings, add a connector whose URL is https://api.wondeya.com/mcp; it will send you to wondeya to sign in and approve, then list the tools. This is the flow OAuth exists for: no header to set, nothing to keep on your machine.

Claude Code

Add it with the CLI (no header this time, because the OAuth handshake replaces it):

claude mcp add --transport http wondeya https://api.wondeya.com/mcp

Run /mcp inside Claude Code and choose to authenticate: it opens your browser for the sign-in and consent, then shows the server as connected with its tools. You can also declare it in a project’s .mcp.json:

{
  "mcpServers": {
    "wondeya": {
      "type": "http",
      "url": "https://api.wondeya.com/mcp"
    }
  }
}

Any other client that supports HTTP MCP

Editors and agents such as Cursor, Windsurf, VS Code, opencode and Codex take the same shape: an HTTP server at the URL, with no Authorization header. When the client first reaches the endpoint it triggers the browser sign-in, and once you approve it holds the token itself.

{
  "mcpServers": {
    "wondeya": {
      "type": "http",
      "url": "https://api.wondeya.com/mcp"
    }
  }
}

The two things that matter everywhere are the URL and the transport (HTTP, not stdio). If your client cannot run the browser OAuth flow, use the stdio bridge below; it performs the handshake for you.

Clients that only speak stdio

Bridge the HTTP endpoint into a stdio process with mcp-remote, which runs the OAuth handshake on your machine and caches the token:

{
  "mcpServers": {
    "wondeya": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.wondeya.com/mcp"]
    }
  }
}

The first run opens your browser to sign in and approve; after that the bridge reuses the cached token and forwards to the same endpoint.

Managing and revoking a connection

Every connection is listed in the console under Configuration → Connected apps, with the scopes it holds. Revoke it there; revocation takes effect on the next request, and the client must sign in again to reconnect. There is no cache to wait out.

Check that it works

Ask your client to list the server’s tools. Every MCP client has a way to show them, and tools/list is the authoritative answer about what this server offers. You should see the agent, site key, project, page, knowledge, image, brand, theme and usage tools. A good first request, because it is read-only and proves the whole chain: “list the pages in my wondeya workspace.”

Troubleshooting

What you see	What it means
The browser never opens	Your client is not running the OAuth flow. Confirm it is configured as an HTTP server (not stdio) and that no stale `Authorization` header is set. Clients that cannot do OAuth should use the `mcp-remote` bridge.
`401` with `wondeya.oauth.unauthorized`	No valid token: the connection was never approved, or it was revoked or expired. Reconnect and approve the consent screen. Every cause answers the same way on purpose.
A tool answers `wondeya.oauth.insufficient_scope`	The connection is valid but was not granted the scope that tool needs. Reconnect and approve the missing scope. Also check your role, since a member can grant read only.
A scope shows dimmed on the consent screen	Your role cannot grant it. An owner or admin grants write; a member grants read only.
`405` on connect	Your client sent `GET` or `DELETE`. This server is stateless and accepts `POST` only: pick the Streamable HTTP transport, not SSE.
`429`	You are over the per-minute allowance for this surface. Slow the loop down; a burst of handshakes plus tool calls is expected, a tight retry loop is not.
The client connects but shows no tools	It is talking to something else. Confirm the URL ends in `/mcp`.
A tool answers with `isError`	That is a business refusal, not a broken connection: read the problem document’s `code` and act on it.

​How connecting works

​Browser assistants: Claude and ChatGPT

​Claude Code

​Any other client that supports HTTP MCP

​Clients that only speak stdio

​Managing and revoking a connection

​Check that it works

​Troubleshooting

How connecting works

Browser assistants: Claude and ChatGPT

Claude Code

Any other client that supports HTTP MCP

Clients that only speak stdio

Managing and revoking a connection

Check that it works

Troubleshooting