Nexus MCP

Nexus MCP connects ChatGPT, Claude, and other MCP clients to the same Nexus data and operations available to the authenticated member. The server exposes a permission-filtered tool catalog for Advertiser, Search, XML, statistics, feeds, and campaigns.

ChatGPT / Claude / custom MCP client
                |
                | Streamable HTTP + OAuth 2.1 with PKCE
                v
    https://mcp.example.com/mcp
                |
                | Nexus tenant, role, module, scope,
                | ownership, confirmation and audit checks
                v
           Nexus backend APIs

ChatGPT is supported

Nexus MCP already implements OAuth discovery, dynamic client registration, authorization code with PKCE S256, opaque access and refresh tokens, and token revocation. It can be connected directly as a ChatGPT plugin. No Nexus API key is pasted into ChatGPT.

Choose your AI client

Client	Nexus support	Start here
ChatGPT plugin	Supported through the built-in OAuth flow	Connect ChatGPT
Claude.ai / Claude Desktop	Supported as a remote custom connector	Connect Claude
Claude Code	Supported as a remote HTTP MCP server	Connect Claude Code
Custom MCP client	Supported through OAuth discovery and Streamable HTTP	Custom client guide

Service addresses

Every customer uses their own domain. Replace the api. subdomain with mcp.:

https://api.example.com  ->  https://mcp.example.com
https://api.example2.com ->  https://mcp.example2.com

Connect advertiser and publisher members through this endpoint:

https://mcp.example.com/mcp

The public guide covers only member connections and permitted /login/* operations. Administrative connections are configured privately by an authorized Nexus administrator from the Account Managers screen.

How authentication works

1. The AI client reads Nexus protected-resource and authorization-server metadata.
2. It dynamically registers a public OAuth client.
3. It creates a PKCE S256 challenge and opens the Nexus authorization flow.
4. Nexus routes the browser to the member authorization page.
5. The user signs in through the normal Nexus frontend if no valid UI session exists.
6. Nexus displays the tenant, callback origin, and requested scopes.
7. After explicit approval, the client receives a one-time code and exchanges it for opaque MCP tokens.
8. Every tool call rechecks tenant, identity, role, modules, scopes, endpoint policy, and ownership in the Nexus backend.

The MCP authorization page never collects a Nexus password. The existing Nexus UI session is validated server-to-server, and Nexus access/refresh JWTs are never returned to the AI client.

OAuth scopes

Scope	Grants
nexus:read	Permitted reads, resources, and catalogued read-only POST queries
nexus:write	State-changing operations after preview and confirmation
nexus:upload	Permitted CSV uploads in addition to write access
offline_access	Refresh tokens for durable sessions and scheduled tasks

If the client does not request a scope, Nexus grants only nexus:read. Ask for write, upload, or offline access only when the workflow genuinely requires it.

What Nexus MCP can do

The visible tools depend on the connected identity and permissions. Major groups include:

• identity, endpoint discovery, operation contracts, help, and form context;
• advertiser campaign list, full configuration, create, update, clone, and status changes;
• Search, XML, and Advertiser reports with correct totals and weighted KPIs;
• Search/XML feed discovery, provider matching, safe preparation, creation, and API diagnostics;
• high-level entity reads and confirmed changes across the permitted Nexus catalog;
• multi-command planning, per-step confirmation, execution, verification, and safe resume;
• constrained scheduled tasks when offline_access is granted;

See Available MCP tools for concrete prompts and the safe workflow.

Read versus change workflow

Reads can run immediately after authorization. Changes are deliberately multi-step:

Understand request
      -> read current state
      -> load operation contract
      -> prepare exact non-secret diff
      -> show user preview
      -> receive explicit confirmation
      -> execute once with approval + idempotency
      -> read back and verify

For one command, Nexus uses nexus_resolve_command. For several independent commands it uses nexus_plan_commands, which preserves order and creates a separate confirmation boundary for each mutation.

Security boundaries

• OAuth tokens are opaque, short-lived, tenant-bound, identity-bound, and resource-bound.
• Authorization codes and refresh tokens are single-use; refresh rotation invalidates the preceding MCP access token.
• A Nexus scope never grants a role or module the user does not already have.
• Sensitive routes such as password reset, API-key management, raw login/refresh, tenant-platform administration, and impersonation are centrally denied.
• Campaign and entity ownership comes from the authenticated backend session, not caller-supplied user IDs.
• Every mutation requires exact authorization, validation, preview, explicit confirmation, idempotency, and verification.
• Credentials, cookies, authorization headers, secret-like values, and request bodies are redacted from audit records.
• Customer hostnames, OAuth issuers, clients, sessions, and stored state are isolated by tenant.

Optional direct JWT mode

Trusted automation can use a Nexus UI access JWT only when the deployment explicitly enables ALLOW_DIRECT_JWT=true:

Authorization: Bearer <nexus-access-jwt>

This is not the normal ChatGPT/Claude setup and it is not a Nexus integration API key. Public client connections should use OAuth so rotation and revocation remain automatic.

Recommended next step

• ChatGPT: connect the Nexus plugin step by step
• Claude: add a remote custom connector
• Tool examples: browse capabilities and prompts
• Problems: follow the troubleshooting checklist