@segnals/mcp

Manage your Segnals trading bots, strategies, PnL, and the strategy marketplace from any AI agent (Claude, Cursor, Claude Code, Windsurf, Copilot, etc.) — securely, by just talking.

Built by Segnals · Secure Algorithmic Trading Ecosystem

Table of Contents

• See It in Action

• What Is This? / What Is Segnals?

• Features & Capability Overview

• Quickstart (60 Seconds)

• Getting Your API Key (Onboarding)

• Installation

• Client Configuration

• Authentication & Scopes

• Tool Reference

• Security Model

• Safety & Disclaimer

• Example Use-Cases & Prompt Library

• Architecture

• Compatibility Matrix

• Troubleshooting

• For AI Agents

• Roadmap

• Contributing & Support

• License

See It in Action

Here is how a conversation with an MCP-enabled agent flows:

Use Case 1: Checking Portfolio Performance

User: How are my bots performing this month?

Agent: (Calls segnals_get_pnl_summary)

Agent: You have 3 active bots running. For the current calendar month:

• Total Net PnL: +$245.50 (+3.4% account gain)

• Win Rate: 68% (17 winning trades, 8 losing trades)

• Drawdown: 1.2% maximum

• Top Performer: Trend Scalper Gold (+$180.20 PnL)

Use Case 2: Strategy Creation with Two-Step Confirmation Gate

User: Set up a new Conservative EURUSD Forex bot with 2:1 Reward ratio.

Agent: (Calls segnals_create_strategy with confirm: false)

Agent: ✋ Preview Strategy Configuration:

• Name: Conservative EURUSD Trend

• Symbol: EURUSD

• Asset Class: Forex (MetaTrader 5)

• Leverage: 1:30

• Risk Parameters: Stop Loss = 20 pips, Take Profit = 40 pips (2:1 Ratio)

• Estimated Drawdown Warning: 1.5%

To proceed and save this bot to your dashboard, please reply with "confirm".

User: Confirm

Agent: (Calls segnals_create_strategy with confirm: true)

Agent: ✅ Strategy has been created successfully. You can find it on your dashboard or manage it here by asking me to list your bots.

What Is This? / What Is Segnals?

Segnals is an institutional-grade, multi-tenant algorithmic trading and AI ecosystem. It enables retail traders and quants to write, backtest, and deploy high-frequency trading (HFT) bots across cryptocurrency exchanges (via CCXT) and Forex brokers (via a custom MetaTrader 5 Redis bridge).

The Segnals MCP Server is a thin, secure gateway designed for the Model Context Protocol (MCP). It exposes a set of strictly typed developer APIs as tools to large language models (LLMs). This allows AI agents to read trading statistics, create strategies, modify parameters, and manage marketplace listings on behalf of the user, using secure, cryptographically hashed user keys.

🔒 Security Boundaries (Can / Can't Do)

• WHAT IT CAN DO:

  • Fetch account balance, statistics, and historical PnL logs.

  • List, query, and monitor active trading bot statuses.

  • Create, modify, start, stop, restart, or delete trading bots.

  • Browse the Strategy Marketplace and copy/purchase strategies.

  • Modify notification preferences and query market prices/sentiment.

• WHAT IT CANNOT DO (Strict Hard Exclusions):

  • ❌ No Fund Movement: Cannot deposit, withdraw, or transfer funds.

  • ❌ No Secret Retrieval: Cannot read, export, or enter API secrets for Bybit/MetaTrader 5. All exchange secrets are configured exclusively in the web dashboard.

  • ❌ No Administrative Overrides: Cannot modify user profile settings, credentials, passwords, or emails.

Features & Capability Overview

The server exposes 36 distinct tools structured across the following trading features:

• Account & Meta: Retrieve subscription tiers, feature flags, active limitations, and system statuses.

• Stats & Drawdowns: Access current balance, historical performance analytics, and trade-by-trade logs.

• Life Cycle Control: Create, update, start, stop, restart, and delete bots.

• Forex & MT5: Inspect broker connectivity and Metatrader 5 account status.

• Indicators & Filters: Bind custom filters (e.g. Bias Engine, Bollinger, EMA cross) to strategy pipelines.

• Copy Trading & Marketplace: Browse listings, copy paid or free strategies, and manage public offerings.

• Market Feed & Knowledge: Query real-time prices, fetch sentiment rankings, and search onboarding guides.

For inputs, outputs, and JSON examples for each tool, see the Tool Reference Guide.

Quickstart (60 Seconds)

1. Get an API Key

Log in to your dashboard at segnals.com, navigate to Settings → API Keys, generate a key, and select the desired scopes (e.g., read:account, read:bots). Copy the token (sk_live_... or sk_test_...).

2. Configure Claude Desktop

Open your Claude Desktop configuration file (see location directories below) and add the server:

{
  "mcpServers": {
    "segnals-mcp": {
      "command": "npx",
      "args": ["-y", "@segnals/mcp"],
      "env": {
        "SEGNALS_API_KEY": "sk_live_your_actual_key_here"
      }
    }
  }
}

3. Verify Connection

Restart Claude Desktop and ask the agent:

"Use segnals_whoami to verify who I am connected as on Segnals."

Getting Your API Key (Onboarding)

To integrate your agent with your account, you must mint a Developer API Key:

1. Navigate to Settings → API Keys on your dashboard.

2. Click Generate Key and assign a descriptive label.

3. Select Scopes: It is recommended to choose only read-only scopes (read:account, read:stats, read:bots) for your first setup. Add write permissions as needed.

4. Specify an optional IP allowlist or expiration date if desired.

5. Click Generate.

6. Copy Token: Copy the displayed token (sk_live_...) immediately. It will only be shown once.

For more details, see the Onboarding Guide.

Installation

You can run the Segnals MCP server using three methods:

Method A: npx (Recommended)

This is the simplest way to run the server. It will download and run the latest version automatically:

export SEGNALS_API_KEY=sk_live_your_key_here
npx -y @segnals/mcp

Method B: From Source (For Developers)

Requires Node.js >= 18.

git clone https://github.com/eidostein/segnals-mcp.git
cd segnals-mcp
npm ci
npm run build
export SEGNALS_API_KEY=sk_live_your_key_here
node dist/index.js

Method C: Docker

We maintain a public Docker image on GHCR:

docker run --rm -it -e SEGNALS_API_KEY=sk_live_your_key_here ghcr.io/eidostein/segnals-mcp:latest

Client Configuration

The server runs on standard input/output (stdio) streams. Depending on your editor or chat interface, add the following configuration:

1. Claude Desktop

File locations:

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

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

Add this entry to your mcpServers object:

{
  "mcpServers": {
    "segnals-mcp": {
      "command": "npx",
      "args": ["-y", "@segnals/mcp"],
      "env": {
        "SEGNALS_API_KEY": "${env:SEGNALS_API_KEY}"
      }
    }
  }
}

(Note: Replace ${env:SEGNALS_API_KEY} with your actual key or define it in your shell profile).

2. Cursor

Navigate to Settings → Features → MCP:

1. Click + Add New MCP Server.

2. Name: segnals

3. Type: command

4. Command: npx -y @segnals/mcp

5. Environment Variables: Key = SEGNALS_API_KEY, Value = sk_live_...

3. Claude Code (CLI)

Install and connect directly from the command line:

claude mcp add segnals-mcp -- npx -y @segnals/mcp

For more details, see the Configuration Guide.

Authentication & Scopes

The server utilizes scoped access tokens to restrict API permissions. The following scopes can be bound to your API key:

For detailed information, see the Authentication Documentation.

Tool Reference

The following table summarizes the 36 tools exposed by the Segnals MCP server:

For complete usage specifications, see docs/TOOLS.md.

Security Model

The Segnals MCP integration enforces safety guidelines:

1. Hashed Key Storage: API keys are hashed with SHA-256 at rest. Plaintext keys are never stored in the database.

2. Explicit Scope Restrictions: Keys are restricted to their defined scopes. If a key is leaked, it can be revoked or rotated instantly without affecting main account passwords.

3. Two-Step Confirmation Gating: Destructive or financially significant tools (e.g., create_bot, start_bot, copy_strategy) require a confirm: true parameter. Calling them without confirm: true returns a safe JSON preview.

4. Exchange Credentials Isolation: Exchange API secrets and MT5 passwords never leave the primary Segnals servers. AI agents can configure where a bot executes, but can never see or export credentials.

5. Per-Key Rate Limiting: The backend limits keys to a default of 120 requests/minute to prevent loop bugs from overloading the API.

6. Immutable Exclusions: Admin functions, billing details, and withdrawal routes are hard-excluded from the API Key pathway.

For further information, see the Safety & Limitations Guide.

Safety & Disclaimer

Example Use-Cases & Prompt Library

You can copy and paste the following prompts to guide your agent:

Strategy Design & Deployment

"Check my active connection status. If connected, list all strategy schemas and help me design a low-risk Grid bot for BTCUSDT on Bybit." Requires: read:bots, write:bots

Performance Review

"Retrieve a summary of my bot performances. Identify which bot has the highest drawdown this week, pull its execution logs, and suggest parameter updates." Requires: read:stats, read:bots

Marketplace Discovery

"Browse the Strategy Marketplace for low-risk, high-rating Forex strategies. Explain the parameters of the top-performing item and copy it to my workspace." Requires: read:marketplace, write:marketplace

Architecture

The Segnals MCP Server acts as an intermediate translator between your local agent and the remote Segnals platform:

┌─────────────────────────────────┐
│        AI Agent / IDE           │ (Claude Desktop, Cursor, etc.)
└────────────────┬────────────────┘
                 │
                 │ stdio (std_in / std_out)
                 ▼
┌─────────────────────────────────┐
│    Segnals MCP Server (Local)   │
└────────────────┬────────────────┘
                 │
                 │ HTTPS (REST API) + Bearer API Key
                 ▼
┌─────────────────────────────────┐
│     Segnals REST API (Remote)   │ (Enforces Rate-Limits, Scopes, and Auditing)
└─────────────────────────────────┘

Compatibility Matrix

Troubleshooting

1. The Server Does Not Appear in Claude Desktop

• Cause: Invalid path configuration or Node.js missing from system path.

• Fix: Verify your Node.js installation by running node -v. Check that the command is configured as "command": "npx" and the args include "-y", "@segnals/mcp". Check the Claude Desktop log files at %APPDATA%\Claude\logs\mcp.log or ~/Library/Logs/Claude/mcp.log.

2. Error Code: 401 Unauthorized

• Cause: Malformed, expired, or incorrect API key format.

• Fix: Ensure your environment key is correctly configured as export SEGNALS_API_KEY=sk_live_... and that the prefix is correct. Make sure the key has not been revoked on the dashboard.

3. Error Code: 403 Forbidden

• Cause: The API key lacks the required scopes for the executed tool.

• Fix: Verify the scope required by the tool (see Tool Reference) and generate a new key on the dashboard with the appropriate scope.

4. Error Code: 429 Too Many Requests

• Cause: Request rate limit exceeded.

• Fix: Reduce the frequency of commands. AI loops can occasionally flood the API. Check that your client logic is not stuck in an execution loop.

For more details, see the Troubleshooting Guide.

For AI Agents

🤖 If you are an AI Agent: Read AGENTS.md and llms.txt first. These files contain specific context on tool naming rules, safety disclaimers, the mandatory confirmation workflow, and advice on choosing the correct API endpoint.

Roadmap

• Phase 4b: Remote OAuth Integration: Connect your account via OAuth 2.1 protocol for zero-install clients. (Planned)

• Advanced Backtesting: Run backtest jobs directly from the command line. (Planned)

• Dynamic Telemetry WebSocket Stream: Fetch sub-millisecond price changes. (Planned)

Contributing & Support

We welcome contributions to the Segnals MCP server:

• Report bugs and request features in GitHub Issues.

• Read CONTRIBUTING.md and CODE_OF_CONDUCT.md.

• For security reports, please refer to SECURITY.md to report vulnerabilities privately.

• Contact support at support@segnals.com.

License

This project is licensed under the MIT License - see the LICENSE file for details.