bluenexus.ai Get API Key

Key Concepts

The mental model you need before going deeper.

MCP (Model Context Protocol)

MCP is an open protocol that lets AI applications discover and call tools on remote servers. Instead of hard-coding API integrations, an AI app sends a JSON-RPC request to an MCP server and gets back structured results. BlueNexus implements an MCP server at https://api.bluenexus.ai/mcp.

Universal MCP Endpoint

BlueNexus's Universal MCP endpoint consolidates access to 100+ services into two tools:

  • use-agent — An AI agent that can access and use the user's connected services. You pass a prompt (e.g., "What's on my Google Calendar today?") and optionally a connector filter (e.g., "google"). The agent identifies the right service, makes the API calls, and returns the result.

  • list-connections — Returns which services the user has connected and their status. Use this to discover what's available before calling use-agent.

This two-tool model keeps your context window small. Instead of loading hundreds of tool definitions from dozens of services, your AI app works with just two tools and delegates the routing to BlueNexus.

Connectors and Connections

Connectors (also called providers) are the services BlueNexus can integrate with — Google Workspace, Slack, GitHub, Notion, etc. These are the same for everyone.

Connections are user-scoped. When your user connects their Google account, that creates a Connection — an encrypted OAuth token pair tied to their account. Connections have a status:

Status Meaning Action
active Working normally None needed
expired Token expired Call PUT /v1/connections/:id/refresh
error Something went wrong User may need to reconnect
revoked User revoked access User must reconnect

Auth Clients

An auth client represents your application in the BlueNexus OAuth system. There are two ways to get one:

  • Dynamic Client Registration (DCR) — MCP clients auto-register by calling POST /v1/auth/register. Assigns the THIRD_PARTY role automatically.
  • Manual registration — Create via the BlueNexus dashboard or POST /v1/auth-clients API. Can be THIRD_PARTY or WHITELABEL_CUSTOMER.

Client Roles

Your auth client's role determines what APIs your app can access:

Role MCP LLM API Use Agents Create Agents White-Label
THIRD_PARTY Yes Yes Yes No No
WHITELABEL_CUSTOMER Yes Yes Yes Yes Yes

THIRD_PARTY is the default for all DCR-registered clients. WHITELABEL_CUSTOMER requires manual registration and hides BlueNexus branding from your users.

Scopes

Scopes control what your app can do with a user's token. You request scopes during OAuth authorization. Key scopes:

Scope Access
universal-mcp-read MCP tool discovery only
universal-mcp-read-write MCP tool discovery and execution
llm-all LLM chat completions
agents-use Chat with existing agents
agents-all Create, update, delete agents
connections Manage service connections
account Read account info
openid / profile / email OpenID Connect identity

Credits

BlueNexus uses a credit-based system for LLM and tool usage:

  • 1 credit = $0.0001 USD
  • New accounts start with 100,000 credits ($10.00)
  • Credit consumption is returned in response headers: X-Credits-Consumed and X-Credits-Remaining
  • When credits run out, the API returns HTTP 402 with a CreditsExhaustedError

OAuth 2.1 with PKCE

BlueNexus uses OAuth 2.1 with mandatory PKCE (Proof Key for Code Exchange, S256 only) for all authorization flows. This means:

  1. Your app generates a random code verifier
  2. Hashes it with SHA-256 to create a code challenge
  3. Sends the challenge in the authorize request
  4. Sends the original verifier when exchanging the code for tokens

This prevents authorization code interception attacks, even for public clients (SPAs, mobile apps).

Well-Known Endpoints

BlueNexus publishes standard discovery documents:

Endpoint Purpose
/.well-known/oauth-authorization-server OAuth server metadata (RFC 8414)
/.well-known/oauth-protected-resource Protected resource metadata (RFC 8707)
/.well-known/openid-configuration OpenID Connect discovery
/.well-known/jwks.json Public keys for token verification
/.well-known/oauth-client Client metadata document

MCP clients use these to auto-discover the auth flow.

White-Label

With the WHITELABEL_CUSTOMER role, you can hide BlueNexus entirely. Your users see your brand throughout the OAuth consent and connection management screens. You configure custom branding (logo, colors, description) on your auth client.

White-Label Guide →

Next Steps