Connector API

Claude / ChatGPT App / MCP

Claude and ChatGPT can connect to Vernclaw through the remote MCP endpoint:

• POST /mcp

The MCP server exposes platform tools plus each active Vernclaw connector as its own MCP tool. For example, seo.website-traffic is exposed as vernclaw_seo_dot_website_dash_traffic with the connector input schema.

• vernclaw_list_connectors
• vernclaw_get_connector_job
• Connector tools generated from active connector IDs

Tool descriptors include OpenAI review annotations. read_only connectors are marked readOnlyHint: true; generation connectors and async job polling are marked as non-read-only because they create jobs, charge credits, or persist results. Vernclaw connector tools are marked non-destructive and open-world because they call managed external providers or public web platforms.

Authenticated installs use OAuth 2.1 with PKCE. Vernclaw publishes the required discovery and OAuth endpoints:

• GET /.well-known/oauth-protected-resource
• GET /.well-known/oauth-authorization-server
• POST /oauth/register
• GET /oauth/authorize
• POST /oauth/token

The OAuth flow links a Claude or ChatGPT user to an existing Vernclaw account and issues a bearer token backed by the same API key runtime used by the CLI. Connector calls still go through the normal install, credit, cache, provider, and audit checks. The token endpoint supports both authorization_code and refresh_token grants so clients can keep an existing install authorized without asking the user to reconnect.

Claude custom connectors can use dynamic client registration, or a user-owned OAuth client. When Claude asks for OAuth credentials in Advanced settings, generate them from API Keys:

• Server URL: https://vernclaw.com/mcp
• OAuth Client ID: your generated client ID
• OAuth Client Secret: your generated client secret

Each generated OAuth client belongs to one Vernclaw user. During authorization, the signed-in Vernclaw account must match the owner of the client ID. OAuth client secrets are not accepted as normal API keys.

Authentication

Connector API requests use the same API key table as the rest of the product.

• Authorization: Bearer <api_key>
• x-api-key: <api_key>

Endpoints

• GET /api/connectors
• GET /api/connectors?format=markdown
• GET /api/connectors/[connectorId]
• GET /api/connectors/[connectorId]?format=markdown
• POST /api/connectors/[connectorId]/invoke
• GET /api/connectors/jobs/[jobId]
• GET /api/connectors/status
• GET /api/connectors/balance (compatibility alias)

Output contract

Connector invocation, job polling, status, and balance endpoints return JSON with content-type: application/json. Successful invoke and job responses return a compact connector data payload with normalized fields for CLI and agent consumption. Full upstream provider payloads are retained in server-side task, audit, and cache records for troubleshooting.

Catalog and describe endpoints return JSON by default. Their format=markdown variants are compatibility views for browser/docs usage only; the CLI consumes JSON and renders any pretty terminal output locally.

The CLI wraps these HTTP payloads as { "status": <http_status>, "data": <payload> } before printing to stdout. When a business error occurs, invoke and job responses still return compact JSON and include x-error-code for machine-readable branching.