Skip to main content
Glama
upvest-mcp-server

upvest-mcp-server

by Shalom2212

upvest-mcp-server

A Model Context Protocol (MCP) server for the Upvest Investment API. It enables LLMs (such as Claude Desktop, Cursor, and Google Gemini) to simulate investment orders, generate RFC 9421-compliant HTTP Message Signatures, and triage webhook delivery anomalies and API rejection codes.


Features

  • Order Simulation & Validation (upvest_simulate_order)

    • Validates 12-character security ISIN formats (ISO 6166).

    • Enforces Upvest trading constraints: fractional orders are restricted to MARKET execution, while LIMIT orders require whole integer units.

    • Calculates mandatory 10% cash buffer reserves on MARKET BUY orders to cover intraday price volatility before routing to the clearing venue.

    • Simulates order lifecycle transitions (NEW → PROCESSING → SUBMITTED_TO_VENUE).

  • HTTP Message Signatures (upvest_signature_generator)

    • Generates RFC 9421 / draft-ietf compliant Signature-Input, Signature, and Digest headers required by the Upvest API gateway.

    • Handles canonical @method, @path, and SHA-256 body digest hashing with cryptographic nonces and timestamps.

  • Webhook Anomaly & Failure Triage (upvest_anomaly_analyzer)

    • Triages webhook delivery anomalies and execution failure codes (e.g. INSUFFICIENT_FUNDS_BUFFER, INVALID_SIGNATURE, OUT_OF_ORDER_WEBHOOK, RATE_LIMIT_EXCEEDED).

    • Provides root-cause analysis, severity ratings, and actionable fixes.


Related MCP server: Stelar Signals MCP

Project Structure

upvest-mcp-server/
├── src/
│   ├── index.ts                  # MCP server entrypoint & stdio transport
│   ├── types.ts                  # Domain interfaces & type definitions
│   └── tools/
│       ├── simulateOrder.ts      # upvest_simulate_order tool
│       ├── signatureGenerator.ts # upvest_signature_generator tool
│       └── anomalyAnalyzer.ts    # upvest_anomaly_analyzer tool
├── dist/                         # Compiled JavaScript distribution
├── client/
│   ├── gemini.py                 # FastMCP + Gemini client example
│   └── requirements.txt          # Python client requirements
├── package.json
└── tsconfig.json

Getting Started

Prerequisites

  • Node.js: v18.0.0 or higher

  • npm: v9.0.0 or higher

Installation & Build

# Clone the repository
git clone https://github.com/Shalom2212/upvest-mcp-server.git
cd upvest-mcp-server

# Install dependencies
npm install

# Build the TypeScript project
npm run build

Running Locally

# Start in production mode
npm start

# Run in development mode with hot reload
npm run dev

Client Configuration

Claude Desktop

Add the server to your claude_desktop_config.json:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "upvest": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/upvest-mcp-server/dist/index.js"]
    }
  }
}

Cursor

Add to your project's .cursor/mcp.json:

{
  "mcpServers": {
    "upvest": {
      "command": "node",
      "args": ["dist/index.js"]
    }
  }
}

Python / Gemini Client

The repo includes a Python client in client/gemini.py demonstrating how to connect to the MCP server using fastmcp and Google's Gemini SDK:

# Install Python dependencies
pip install -r client/requirements.txt

# Set your Gemini API key
export GEMINI_API_KEY="your-api-key"

# Run the client
python client/gemini.py

Available MCP Tools

1. upvest_simulate_order

Simulates an investment order against Upvest trading and risk rules.

Argument

Type

Required

Description

isin

string

Yes

12-character alphanumeric security ISIN (e.g. US0378331005)

side

"BUY" | "SELL"

Yes

Order side

type

"MARKET" | "LIMIT"

Yes

Execution type

quantity

number

Yes

Number of shares (fractional allowed for MARKET)

available_cash

number

Yes

Account available cash balance in EUR

limit_price

number

Optional

Limit price per share in EUR (mandatory for LIMIT orders)

account_id

string

Optional

Upvest account UUID (generates sandbox account if omitted)

2. upvest_signature_generator

Generates RFC 9421 HTTP Message Signature headers.

Argument

Type

Required

Description

method

"GET" | "POST" | "PUT" | "PATCH" | "DELETE"

Yes

HTTP request method

path

string

Yes

Request path and query string (e.g. /orders)

payload

string

Optional

JSON stringified request body

key_id

string

Optional

Upvest API Key ID

3. upvest_anomaly_analyzer

Diagnoses Upvest webhook failures and error states.

Argument

Type

Required

Description

event_type

string

Yes

Webhook event name (e.g. order.cancelled)

error_code

string

Yes

Upvest error identifier (e.g. INSUFFICIENT_FUNDS_BUFFER)

payload_diff

string

Optional

Raw payload or error message snippet


Example Usage

Pre-Trade Buffer Validation & Signature Generation

Prompt:
"Simulate a market buy order for 12.5 shares of Apple (ISIN US0378331005) with 2,000 EUR available cash, and generate the required RFC 9421 headers."

Claude Response:

Order Rejection (Buffer Check):

  • Estimated Cost (12.5 × €150.00): €1,875.00

  • Mandatory 10% Volatility Buffer: €187.50

  • Total Required: €2,062.50 | Available Cash: €2,000.00 ❌ (Shortfall: €62.50)

*Adjusting to 12.0 shares passes the reserve check (€1,980.00 total) and generates valid gateway

{
  "Signature-Input": "sig1=(\"@method\" \"@path\" \"digest\");keyid=\"upv_sec_key_sandbox_01J9X8\";created=1792357433;nonce=\"749c71805c96404c\"",
  "Signature": "sig1=:qy/Qusgf6IfSYx1ocPukF6IBqEHxqw3Ud3tZXqM/wV8=:",
  "Digest": "SHA-256=R8usq2iX0dFXmPtXdFOoGMlyq44ObFOgELhUdn2ZIvo=",
  "Content-Type": "application/json"
}

License

This project is licensed under the MIT License.

Available Tools

3 tools
upvest_anomaly_analyzerC

Auto-triages Upvest webhook delivery anomalies, out-of-order state transitions, and execution failure codes.

Inputs: error_code (required), event_type (required), payload_diff.

upvest_signature_generatorA

Generates RFC/IETF draft compliant HTTP Message Signature headers (v15/v6) required for Upvest API requests and webhook handlers.

Inputs: path (required), method (required), key_id, payload.

upvest_simulate_orderB

Validates and simulates an investment order against Upvest Investment API rules (ISIN check, limits, and cash buffer verification).

Inputs: isin (required), side (required), type (required), quantity (required), +3 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool targets a clearly different concern: order pre-validation, cryptographic request signing, and webhook/execution anomaly triage. An agent can confidently pick the right tool from the name and description with no overlap.

    Naming Consistency4/5

    All names use a consistent upvest_ snake_case prefix, but the stems mix verb_noun (simulate_order) with agent-noun forms (signature_generator, anomaly_analyzer). Minor stylistic deviation, still fully readable and predictable.

    Tool Count3/5

    Three tools is thin for a server claiming to cover Upvest investment API integration, order handling, signing, and anomaly triage. Each tool earns its place, but the surface feels like a small helper bundle rather than a complete integration.

    Completeness2/5

    There is no tool to actually create, submit, fetch, or cancel an order, nor to list accounts, instruments, or portfolios — only a simulator, a signer, and an anomaly analyzer. An agent would hit dead ends for the core order lifecycle and would have to fall back to raw API calls.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to securely trade on Hyperliquid perpetual exchange, including order placement, position management, market data retrieval, and vault operations via natural language.
      29 PyPI
      24
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables natural-language paper trading with per-user JWT authentication, allowing simulated market quotes, buy/sell orders, portfolio tracking, and order history through Claude.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables autonomous financial agents to submit payment webhooks, ledger entries, or transaction streams and receive balanced journal records, risk verification dossiers, and detection of card-testing clusters, volume spikes, and account takeovers.
      7
      MIT