MCP server

Six Model Context Protocol tools for AI agent hosts — run it locally over stdio, or connect the hosted server over OAuth with no key to paste.

wellmarked-mcp exposes the API as Model Context Protocol tools: extract, bulk, crawl, get_job, wait_for_job, and get_usage.

Local (stdio)

For Claude Desktop, Claude Code, Cursor, and any host that launches a local MCP process.

WELLMARKED_API_KEY=wm_... npx -y wellmarked-mcp

As a host config entry:

{
  "mcpServers": {
    "wellmarked": {
      "command": "npx",
      "args": ["-y", "wellmarked-mcp"],
      "env": { "WELLMARKED_API_KEY": "wm_..." }
    }
  }
}

Remote (Streamable HTTP)

A hosted endpoint for hosts that support remote MCP servers, such as Claude.ai custom connectors:

https://mcp.wellmarked.io

POST the MCP payload to the root. There is no key to paste — it uses OAuth, so the user signs in and approves scopes in a browser.

The /mcp path still works

https://mcp.wellmarked.io/mcp is served as a permanent compatibility alias, so any connector added before the root became canonical keeps working unchanged. New connectors should use the root, which is also the OAuth resource identifier.

The OAuth flow

Discovery

The host fetches https://mcp.wellmarked.io/.well-known/oauth-protected-resource, which points at the API as the authorization server and reports the resource identifier as https://mcp.wellmarked.io — the root, no trailing slash. An unauthenticated request gets 401 with WWW-Authenticate: Bearer resource_metadata=….

Registration

The host reads https://api.wellmarked.io/.well-known/oauth-authorization-server, registers itself dynamically via POST /oauth/register (RFC 7591), and sends the user to GET /oauth/authorize with a PKCE challenge.

The user signs in to wellmarked.io and approves the requested scopes — extract, bulk, crawl. Never keys.

Token exchange

The host exchanges the authorization code at POST /oauth/token for a scoped access token — a wm_ key that expires in one hour — plus a rotating refresh token.

The access token is an ordinary API key with an expiry, so the MCP server just forwards it as a Bearer. The remote server runs stateless — a fresh session per request — so an expired token returns a clean 401 and the host refreshes.

Direct API callers need none of this

OAuth exists so an agent host can onboard a user through a browser instead of a pasted key. If you are calling the HTTP API or using an SDK, use a Bearer key — see Authentication.

Full reference

wellmarked-mcp on npm

On this page