Architecture

How requests flow through BlueNexus from your app to the user's connected services and back.

Request Flow

Your App POST /mcp (JSON-RPC 2.0, Bearer token)

Auth Guard JWT RS256 verification

Credit Guard balance > 0

MCP Server Per-request instance

use-agent

ReAct Agent LLM reasoning

E2B Sandbox TS / Python / Bash

Remote MCP Direct proxy

list-connections

Sanitizer Token redaction, 50KB truncation

JSON-RPC Response

The Two-Tool Model

Instead of exposing hundreds of individual tool definitions, BlueNexus consolidates everything into two tools:

`use-agent`

An AI agent that accepts a natural language prompt and routes it to the right service(s).

`list-connections`

Returns which services the user has connected and their status.

This matters because:

Context window efficiency — Two tool definitions instead of hundreds. The BlueNexus agent handles routing internally.
Multi-service coordination — A single use-agent call can span multiple services ("Get my calendar events and post a summary to Slack").
Dynamic tool discovery — The agent discovers available tools at execution time based on the user's active connections.

How `use-agent` Works

Prompt injection check

The prompt is scanned for injection attacks. High-risk prompts are blocked.

Provider discovery

The agent checks which services the user has connected and selects the relevant one(s).

ReAct execution

The agent uses a Reasoning + Acting (ReAct) pattern: it reasons about what to do, selects tools, executes them, and iterates until it has a complete answer.

Tool execution

Individual service tools run in either:

E2B sandboxes — Isolated containers running TypeScript, Python, or Bash (30-second timeout)
Remote MCP servers — Direct MCP proxy to external service endpoints

Response sanitization

Sensitive tokens are redacted (OAuth tokens, API keys, etc.) and the response is truncated to 50KB to prevent context window overflow.

Credit deduction

Credits are consumed based on LLM token usage.

Response Formats

JSON

Single JSON-RPC response. Best for simple integrations.

X-Response-Format: json

SSE (Server-Sent Events)

Streaming response with progress notifications during long-running agent execution.

Accept: application/json, text/event-stream

REST API Architecture

Beyond MCP, the REST API follows standard patterns:

Property	Value
Base URL	`https://api.bluenexus.ai/api/v1`
Auth	Bearer token in `Authorization` header
Content-Type	`application/json`
Pagination	`page` and `limit` query parameters
Sorting	`sortBy` and `sortOrder` query parameters
Error format	`{ "error": "...", "message": "...", "statusCode": 401 }`