> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiusd.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Hub API

> Direct API access for custom agents

## What is MCP Hub

HTTP server implementing Model Context Protocol (MCP) that provides AI agents with access to trading services through standardized tool calls.

**Protocol:** JSON-RPC 2.0 over HTTP

**Endpoints:**

* Production: `https://mcp.alpha.dev/api/mcp-hub/mcp`
* Development: `https://dev.alpha.dev/api/mcp-hub/mcp`

<Note>
  Authentication required. Contact support for API access.
</Note>

## Quick Start

### List Available Tools

```bash theme={null}
curl -X POST https://mcp.alpha.dev/api/mcp-hub/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'
```

### Call a Tool

```bash theme={null}
curl -X POST https://mcp.alpha.dev/api/mcp-hub/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "genalpha_solchef_get_tokens_market_cap",
      "arguments": {
        "limit": 10
      }
    }
  }'
```

## Tool Naming Convention

All tools follow the pattern: `genalpha_{service}_{action}`

**Examples:**

* `genalpha_tim_execute_intent` - Execute trading intent
* `genalpha_aiusd_get_portfolio` - Get portfolio balance
* `genalpha_solchef_get_tokens_market_cap` - Get token market caps

## Available Services

<CardGroup cols={3}>
  <Card title="TIM" icon="bolt">
    Trading Intent Model

    Prefix: `genalpha_tim_*`
  </Card>

  <Card title="AIUSD" icon="coins">
    Trading & Portfolio

    Prefix: `genalpha_aiusd_*`
  </Card>

  <Card title="Solchef" icon="chart-line">
    Market Data

    Prefix: `genalpha_solchef_*`
  </Card>
</CardGroup>

## Integration Examples

### With Claude Desktop

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "aiusd": {
      "url": "https://mcp.alpha.dev/api/mcp-hub/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}
```

### With Anthropic SDK

```typescript theme={null}
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

const response = await client.messages.create({
  model: "claude-3-5-sonnet-20241022",
  max_tokens: 4096,
  tools: [{
    type: "custom",
    name: "mcp",
    mcp_server: {
      url: "https://mcp.alpha.dev/api/mcp-hub/mcp",
      transport: "http",
      headers: {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }],
  messages: [{
    role: "user",
    content: "What are the top 10 tokens by market cap?"
  }]
});
```

### With MCP Inspector

Test your integration interactively:

```bash theme={null}
npm install -g @modelcontextprotocol/inspector
npx @modelcontextprotocol/inspector
```

**Configuration:**

* Transport: HTTP
* URL: `https://mcp.alpha.dev/api/mcp-hub/mcp`
* Auth: Bearer token required

## Response Format

All tool calls return JSON-RPC 2.0 responses:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{...tool response data...}"
      }
    ],
    "isError": false
  }
}
```

## Error Handling

Errors follow JSON-RPC 2.0 error format:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": -32600,
    "message": "Invalid request",
    "data": {
      "details": "Missing required parameter"
    }
  }
}
```

## Authentication

MCP Hub supports Bearer token authentication:

```bash theme={null}
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://mcp.alpha.dev/api/mcp-hub/mcp
```

Contact support for API access credentials.

## Running Locally

For local development and testing:

### Prerequisites

* Rust toolchain
* `just` command runner (optional)

### Start the Server

```bash theme={null}
git clone https://github.com/galpha-ai/mcp-hub
cd mcp-hub

# Run with local config
just run-local

# Or with cargo
cargo run -- --config config/mcp-hub.local.yaml
```

Local server runs on `http://127.0.0.1:3000/mcp`

<Note>
  Local development uses passthrough authentication. Production requires valid Bearer tokens.
</Note>

## Tool Reference

### TIM Tools

**genalpha\_tim\_execute\_intent** - Execute trading intent

Supports:

* Immediate swaps
* Prediction markets (Polymarket)
* Perpetual futures (HyperLiquid)
* Spot orders (HyperLiquid)
* Conditional orders

### AIUSD Tools

**genalpha\_aiusd\_get\_portfolio** - Get account balance

**genalpha\_aiusd\_get\_transactions** - Get transaction history

### Solchef Tools

**genalpha\_solchef\_get\_tokens\_market\_cap** - Get top tokens by market cap

Parameters:

* `limit` (number): Number of tokens to return

<Card title="Full API Reference" icon="book" href="/api">
  Complete tool catalog with parameters
</Card>

## Best Practices

<AccordionGroup>
  <Accordion title="Use Structured Logging">
    Enable debug logging to see tool calls:

    ```bash theme={null}
    RUST_LOG=debug cargo run
    ```
  </Accordion>

  <Accordion title="Handle Errors Gracefully">
    Always check `isError` field in responses and handle error cases.
  </Accordion>

  <Accordion title="Test with Inspector">
    Use MCP Inspector to test tool calls before integrating into your application.
  </Accordion>

  <Accordion title="Secure Your Tokens">
    Never commit Bearer tokens to version control. Use environment variables.
  </Accordion>
</AccordionGroup>