# nexus-xyz/nexus-exchange-mcp architecture

> Architecture diagram of the GitHub repository nexus-xyz/nexus-exchange-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nexus-xyz/nexus-exchange-mcp
- Repository: https://github.com/nexus-xyz/nexus-exchange-mcp

## Overview

Nexus Exchange MCP Server exposes exchange API operations as tools for AI agents: callers connect over stdio or hosted Streamable HTTP, discover and invoke validated tools, and receive market, account, trading, funding, or bridge results. The shared server dispatches tool handlers to an ExchangeClient, which selects a configured network target and makes public or signed gateway requests. The README documents a broad tool surface; the excerpts do not show every handler, so domain capabilities are grouped rather than mapped endpoint by endpoint.

Main entry points: [`src/tools/index.ts`](https://github.com/nexus-xyz/nexus-exchange-mcp/blob/main/src/tools/index.ts) (Tool definitions), [`src/client.ts`](https://github.com/nexus-xyz/nexus-exchange-mcp/blob/main/src/client.ts) (Exchange client), [`src/server.ts`](https://github.com/nexus-xyz/nexus-exchange-mcp/blob/main/src/server.ts) (MCP server), [`src/http.ts`](https://github.com/nexus-xyz/nexus-exchange-mcp/blob/main/src/http.ts) (HTTP sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["MCP entry points"]
  node_stdio["stdio entry<br/>[index.ts]"]
  node_http_entry["HTTP entry<br/>[http-index.ts]"]
  node_http["HTTP sessions<br/>[http.ts]"]
end

subgraph group_dispatch["Tool dispatch"]
  node_server["MCP server<br/>[server.ts]"]
  node_tools["Tool definitions<br/>[index.ts]"]
end

subgraph group_domain["Exchange capabilities"]
  node_market["Market data<br/>[index.ts]"]
  node_account["Account data<br/>[index.ts]"]
  node_orders["Order trading<br/>[index.ts]"]
  node_funding["Funding operations<br/>[index.ts]"]
  node_bridge["Bridge operations<br/>[index.ts]"]
  node_admin["Admin tools<br/>[index.ts]"]
end

subgraph group_transport["API access"]
  node_config["Runtime config<br/>[config.ts]"]
  node_networks["Network targets<br/>[networks.ts]"]
  node_client["Exchange client<br/>[client.ts]"]
end

node_agent(("AI agent"))
node_exchange["Exchange gateway"]

node_agent -->|"connects via stdio"| node_stdio
node_agent -->|"sends MCP requests"| node_http
node_stdio -->|"creates and connects"| node_server
node_http_entry -->|"starts listener"| node_http
node_http -->|"creates and connects"| node_server
node_server -->|"loads configuration"| node_config
node_config -->|"resolves target"| node_networks
node_server -->|"constructs client"| node_client
node_server -->|"lists and dispatches"| node_tools
node_tools -->|"defines"| node_market
node_tools -->|"defines"| node_account
node_tools -->|"defines"| node_orders
node_tools -->|"defines"| node_funding
node_tools -->|"defines"| node_bridge
node_tools -->|"defines"| node_admin
node_market -->|"requests market data"| node_client
node_account -->|"requests account data"| node_client
node_orders -->|"submits order actions"| node_client
node_funding -->|"requests funding actions"| node_client
node_bridge -->|"requests bridge actions"| node_client
node_admin -->|"requests admin actions"| node_client
node_client -->|"sends API requests"| node_exchange

click node_stdio "https://github.com/nexus-xyz/nexus-exchange-mcp/blob/main/src/index.ts"
click node_http_entry "https://github.com/nexus-xyz/nexus-exchange-mcp/blob/main/src/http-index.ts"
click node_http "https://github.com/nexus-xyz/nexus-exchange-mcp/blob/main/src/http.ts"
click node_config "https://github.com/nexus-xyz/nexus-exchange-mcp/blob/main/src/config.ts"
click node_networks "https://github.com/nexus-xyz/nexus-exchange-mcp/blob/main/src/networks.ts"
click node_server "https://github.com/nexus-xyz/nexus-exchange-mcp/blob/main/src/server.ts"
click node_tools "https://github.com/nexus-xyz/nexus-exchange-mcp/blob/main/src/tools/index.ts"
click node_client "https://github.com/nexus-xyz/nexus-exchange-mcp/blob/main/src/client.ts"
click node_market "https://github.com/nexus-xyz/nexus-exchange-mcp/blob/main/src/tools/index.ts"
click node_account "https://github.com/nexus-xyz/nexus-exchange-mcp/blob/main/src/tools/index.ts"
click node_orders "https://github.com/nexus-xyz/nexus-exchange-mcp/blob/main/src/tools/index.ts"
click node_funding "https://github.com/nexus-xyz/nexus-exchange-mcp/blob/main/src/tools/index.ts"
click node_bridge "https://github.com/nexus-xyz/nexus-exchange-mcp/blob/main/src/tools/index.ts"
click node_admin "https://github.com/nexus-xyz/nexus-exchange-mcp/blob/main/src/tools/index.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_stdio,node_http_entry,node_http toneBlue
class node_server,node_tools toneAmber
class node_market,node_account,node_orders,node_funding,node_bridge,node_admin toneMint
class node_config,node_networks,node_client toneRose
class node_agent,node_exchange toneIndigo
```

## Components

### MCP entry points

- [stdio entry](https://github.com/nexus-xyz/nexus-exchange-mcp/blob/main/src/index.ts): `src/index.ts`
- [HTTP entry](https://github.com/nexus-xyz/nexus-exchange-mcp/blob/main/src/http-index.ts): `src/http-index.ts`
- [HTTP sessions](https://github.com/nexus-xyz/nexus-exchange-mcp/blob/main/src/http.ts): `src/http.ts`

### Tool dispatch

- [MCP server](https://github.com/nexus-xyz/nexus-exchange-mcp/blob/main/src/server.ts): `src/server.ts`
- [Tool definitions](https://github.com/nexus-xyz/nexus-exchange-mcp/blob/main/src/tools/index.ts): `src/tools/index.ts`

### Exchange capabilities

- [Market data](https://github.com/nexus-xyz/nexus-exchange-mcp/blob/main/src/tools/index.ts): `src/tools/index.ts`
- [Account data](https://github.com/nexus-xyz/nexus-exchange-mcp/blob/main/src/tools/index.ts): `src/tools/index.ts`
- [Order trading](https://github.com/nexus-xyz/nexus-exchange-mcp/blob/main/src/tools/index.ts): `src/tools/index.ts`
- [Funding operations](https://github.com/nexus-xyz/nexus-exchange-mcp/blob/main/src/tools/index.ts): `src/tools/index.ts`
- [Bridge operations](https://github.com/nexus-xyz/nexus-exchange-mcp/blob/main/src/tools/index.ts): `src/tools/index.ts`
- [Admin tools](https://github.com/nexus-xyz/nexus-exchange-mcp/blob/main/src/tools/index.ts): `src/tools/index.ts`

### API access

- [Runtime config](https://github.com/nexus-xyz/nexus-exchange-mcp/blob/main/src/config.ts): `src/config.ts`
- [Network targets](https://github.com/nexus-xyz/nexus-exchange-mcp/blob/main/src/networks.ts): `src/networks.ts`
- [Exchange client](https://github.com/nexus-xyz/nexus-exchange-mcp/blob/main/src/client.ts): `src/client.ts`

### Other components

- **AI agent**
- **Exchange gateway**

## Connections

- AI agent → stdio entry: connects via stdio
- AI agent → HTTP sessions: sends MCP requests
- stdio entry → MCP server: creates and connects
- HTTP entry → HTTP sessions: starts listener
- HTTP sessions → MCP server: creates and connects
- MCP server → Runtime config: loads configuration
- Runtime config → Network targets: resolves target
- MCP server → Exchange client: constructs client
- MCP server → Tool definitions: lists and dispatches
- Tool definitions → Market data: defines
- Tool definitions → Account data: defines
- Tool definitions → Order trading: defines
- Tool definitions → Funding operations: defines
- Tool definitions → Bridge operations: defines
- Tool definitions → Admin tools: defines
- Market data → Exchange client: requests market data
- Account data → Exchange client: requests account data
- Order trading → Exchange client: submits order actions
- Funding operations → Exchange client: requests funding actions
- Bridge operations → Exchange client: requests bridge actions
- Admin tools → Exchange client: requests admin actions
- Exchange client → Exchange gateway: sends API requests