Skip to main content
Glama
Shalom2212

upvest-mcp-server

by Shalom2212
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

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: ai-trader

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
error_codeYesUpvest error identifier (e.g. INSUFFICIENT_FUNDS_BUFFER, INVALID_SIGNATURE)
event_typeYesWebhook event (e.g., order.cancelled, execution.rejected, webhook.failed)
payload_diffNoOptional raw error message or JSON payload for additional triage context

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. 'Auto-triages' is ambiguous about whether it only classifies/diagnoses or also mutates state or triggers remediation, and it discloses nothing about permissions, side effects, or rate limits. For an unannotated tool with an ambiguous mutating-sounding verb, this is a significant gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler or redundancy. It is efficient, though arguably terse given the tool's ambiguity rather than genuinely complete.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no annotations and no output schema, the description should explain what triage produces (a classification, a recommendation, a mutation) and any return behavior. It instead stops at the one-line summary, leaving the agent unable to predict the outcome of a call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and all three parameters are documented in the schema, so the baseline is 3. The description adds no syntax, format, or example detail beyond the schema's own parameter descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('auto-triages') plus the resource categories it acts on (webhook delivery anomalies, out-of-order state transitions, execution failure codes). The purpose is clear and clearly distinct from siblings like upvest_simulate_order and upvest_signature_generator, though it never names or contrasts those siblings explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance: no indication of when to reach for this tool versus simulate_order or signature_generator, no prerequisites, and no exclusions. The agent is left to infer the triggering context entirely.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

upvest_signature_generatorA

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

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesRequest URL path and query string (e.g. /orders or /users)
key_idNoUpvest Client API Key ID (defaults to sandbox key if omitted)
methodYesHTTP request method
payloadNoJSON stringified request payload body

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must carry the full behavioral burden. It discloses the output type (signature headers) and compliance standards (RFC/IETF drafts v15/v6), but omits auth requirements (e.g., whether a secret key is needed beyond key_id), whether the operation has side effects, and error behavior. It is adequate but leaves clear gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence with no redundant or vague wording. Every phrase earns its place by specifying verb, resource, standards, and context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple 4-parameter tool with no output schema and no annotations, the description should explain the return format and any prerequisites (e.g., secret key configuration). It only implies the output and omits these details, leaving an adequate but incomplete picture.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds no further meaning to the parameters beyond what the schema already documents (method, path, key_id, payload).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Generates') and resource ('HTTP Message Signature headers'), with precise qualifiers ('RFC/IETF draft compliant (v15/v6)') and usage context ('required for Upvest API requests and webhook handlers'). This clearly distinguishes it from the sibling tools, which concern order simulation and anomaly analysis.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear context: the tool is needed for Upvest API requests and webhook handlers. No explicit when-not or alternative tools are named, but the siblings serve entirely different purposes, so no further routing guidance is necessary.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

upvest_simulate_orderB

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

ParametersJSON Schema
NameRequiredDescriptionDefault
isinYes12-character alphanumeric security ISIN (e.g. US0378331005)
sideYesOrder side (BUY or SELL)
typeYesOrder execution type (MARKET or LIMIT)
quantityYesUnit share quantity (fractional allowed for MARKET, integer only for LIMIT)
account_idNoUpvest account UUID (generates a sandbox account ID if omitted)
limit_priceNoLimit price per share in EUR (mandatory for LIMIT orders)
available_cashYesAccount available cash balance in EUR

TDQS

B3.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses the validation checks (ISIN, limits, cash buffer) and 'simulates' implies no execution side effects, but it omits auth requirements, idempotency, error behavior, and result format. It adds useful behavioral context but is incomplete.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence that states the core action first and contains zero filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The input schema is fully documented and no output schema exists, but the description still lacks usage guidance, side-effect clarity, and return-value expectations. For a seven-parameter tool with no annotations, more context would help an agent call it confidently.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all seven parameters. The description mentions checks involving ISIN, limits, and cash buffer, but adds no syntax, format, or dependency detail beyond what the schema provides; baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Uses a specific verb phrase ('validates and simulates') with a clear resource ('investment order') and scope ('against Upvest Investment API rules'). It does not explicitly differentiate from the sibling tools, but the resource is distinct enough; calibration treats clear verb+resource without sibling naming as a 4.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides no when-to-use guidance, no alternatives, and no prerequisites. The word 'simulates' implies pre-trade validation, but the description never states when an agent should call this tool versus placing an order or using a sibling tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 3 tool updatesv1.0.0
    • First observedupvest_anomaly_analyzer
    • First observedupvest_signature_generator
    • First observedupvest_simulate_order
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

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 issues

Resources

Related MCP Connectors

Related MCP Servers

  • hyperliquid-mcp

    edkdev
    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.
    16 PyPI
    24
    MIT

  • ai-trader

    whchien
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI assistants like Claude to run backtests, fetch market data, list strategies, and analyze trading algorithms via natural language.
    1,113
    GPL 3.0

  • genpark-fintech-webhook

    Alpha-Park
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables secure ingestion and validation of payment webhooks using HMAC-SHA256 signatures, replay tolerance, and atomic idempotency locking to prevent duplicate financial transactions. It provides deterministic ledger integrity and risk auditing for autonomous financial agents and payment rails.
    7
    MIT