How to build trading agents with MCP tools

MCP trading tools let an AI agent in Claude, Cursor, or any compatible client place and manage trades across stocks, crypto, perpetual futures, options, and prediction markets through a single interface. Instead of writing custom brokerage wrappers for every editor and venue, developers expose Felix's normalized API as standard MCP tools that accept plain dollar amounts and return unified position data. The agent never takes custody of funds because it operates within scoped keys and owner approved limits while the underlying wallet remains under the owner's control. Trading can lose money, including your entire budget, so any live deployment should be preceded by thorough paper testing and strict risk controls. This guide walks through connection patterns, permission scoping, testing workflows, and fault handling for developers building agentic trading systems.

What are MCP trading tools and why do they matter?

Model Context Protocol is a standard for connecting AI applications to external data sources and tools. Felix implements an MCP server that publishes a schema describing each trading operation, such as reading balances, fetching market data, and placing orders. The AI client uses this schema to present the tools to the language model, which then decides when to invoke them based on the user's prompt. This means the agent reasons about the goal and selects the correct tool, rather than the developer writing explicit imperative code for every action. The tool descriptions and parameter names are designed to be unambiguous. Felix optimizes them so the model understands that sizes are expressed in US dollars, that markets are typed by asset class, and that certain tools are read only. The normalization layer is the key benefit. A tool call for a stock, a crypto spot position, or a perpetual future uses the same parameter shape. The developer does not need to teach the agent about lot sizes, tick sizes, or margin tiers. The infrastructure handles the translation. This uniformity is what makes building a stock trading agent with MCP conceptually similar to building an agent for any other asset class. Whether you are automating a single strategy or a complex multi market system, the MCP layer removes integration plumbing and lets the agent focus on economic reasoning.

How does a trading agent connect through MCP?

The developer adds the Felix MCP server to the client's configuration, providing the API key and endpoint. Once the client restarts, the tools appear in the agent's context and the model can begin calling them. The agent does not need to know which specific venue will clear the trade. It simply specifies the market type, symbol, side, and dollar size. The infrastructure resolves the rest. This abstraction is useful, but it also means the developer should verify that the agent understands the difference between market types. An agent that conflates stocks with perpetual futures might apply incorrect reasoning about leverage or settlement. The MCP layer does not remove the need for domain knowledge; it removes the need for custom wrappers. For teams running multiple agents, the same MCP server can be instantiated with different scoped keys, making it simple to build multi-agent trading systems through a single API. The exact request schema is in the docs; the shape looks like this.

curl -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "market_type": "perps",
    "symbol": "BTC",
    "side": "buy",
    "dollar_size": 250
  }' \
  https://api.felix.trade/...

The response returns a normalized status, an order identifier, and the filled dollar amount, which the agent can use to update its internal state or present to the user. Developers can also fall back to the REST API directly for headless automation or webhook workflows if an MCP client is not involved. For most editor based development, the MCP path is the fastest way to get an agent from prompt to executed order.

What permissions should you scope for a trading agent?

Scoped keys are the foundation of safe agentic trading. When a developer creates an API key for an MCP agent, they choose which markets it can access, whether it can read, trade, or both, and which symbols or asset classes are permitted. The key cannot authorize withdrawals. Withdrawal addresses are approved by the owner out of band, so even if the agent is compromised, it cannot sweep funds to an external wallet. Budget caps are set in US dollars. A cap might allow the agent to place up to one thousand dollars in total open orders, or limit daily notional turnover. Position limits prevent oversized concentration. These limits are evaluated in real time at the infrastructure level. If an agent attempts to exceed a cap, the request is rejected before it reaches the market. This is a hard limit, not a suggestion.

• ·Start with read-only keys for analysis and market data.
• ·Enable trading on a single market type with a small budget.
• ·Restrict symbols or asset classes to the intended universe.
• ·Set hard budget caps and position limits before the first order.
• ·Document the scope in a runbook and review it weekly.

Developers should also consider rate limits as a form of scope. An agent that pings the API too frequently might not be trading aggressively; it might be stuck in a loop. Setting a reasonable request cap per minute prevents runaway tool calls. It is usually wise to start with read only scopes so the agent can analyze balances and market data before any capital is at risk. Once the behavior is predictable, the developer can expand the scope to include trading on a single market type with a small budget. This gradual expansion is easier to audit and rollback than giving a new agent full access on day one. Every scope change should be deliberate, documented, and paired with a corresponding safety control.

How do you test an MCP trading agent before live markets?

Paper trading is the starting point. Felix provides paper environments where the agent can exercise the full MCP tool chain against simulated market data and matching. The agent places orders, sees fills, and manages virtual positions, but no real money moves. This lets developers test prompt engineering, tool selection, and error handling without financial loss. The transition from paper to live is explicit. A key must be authorized for live trading by the owner; an MCP agent cannot silently promote itself from simulation to real money. This boundary protects against configuration mistakes. During testing, observe how the agent handles ambiguity. If a prompt says "buy a little" the agent should either ask for clarification or fall back to a predefined default size, not guess an arbitrary amount. Paper trading should mirror the live workflow as closely as possible. Use the same prompts, the same tool configurations, and the same MCP client. Introduce edge cases deliberately. Ask the agent to handle a rejected order, a partial fill, or a prompt that requests a trade exceeding the budget cap. Observe whether the agent recovers gracefully or enters a retry loop. Test the kill switch in paper mode to confirm it behaves as expected. Because paper trading changes when AI agents trade real money, the emotional and financial stakes differ, but the mechanics should be identical. Developers should keep a test log comparing paper outputs to expected live outputs. When you are ready to go live, clone the paper key configuration, tighten the budget to a small amount, and authorize it explicitly. Never reuse a paper prompt verbatim without re-reading it, because live market conditions and liquidity can alter execution quality.

What safety controls keep MCP trading within limits?

Infrastructure level controls are more reliable than prompt level instructions. Felix enforces budget caps, position limits, and allowed market lists at the API key level, so even a misinformed or jailbroken agent cannot exceed them. An exit plan can be configured to flatten positions under defined conditions, such as a drawdown threshold or a scheduled close. The panic switch, often called a kill switch, immediately cancels open orders, flattens positions, and revokes the API key. This is a critical circuit breaker for MCP workflows because the agent may act quickly and autonomously once a tool is invoked. Noncustodial architecture means the owner retains the wallet and the private keys. The agent spends from an allowance, not from a pool it controls. Because withdrawal addresses are owner approved only, the worst case scenario is limited to the scoped budget, not the entire wallet balance.

• ·Budget caps limit total deployed capital.
• ·Position limits prevent concentration in a single instrument.
• ·Exit plans close positions when drawdown thresholds are hit.
• ·The panic switch flattens everything and revokes the key immediately.
• ·Withdrawal addresses approved by the owner prevent fund exfiltration.

The panic switch is designed to be reachable even if the agent is unresponsive. Because MCP agents operate inside an editor, the owner might not have a separate dashboard open. Felix provides a direct way to trigger the switch from a mobile or web interface without relying on the MCP client. Developers should treat these controls as part of the system design, not as afterthoughts. Building a practical security checklist for AI trading agents before going live is a standard part of the workflow. Review caps daily when an agent is new, and tighten scopes before expanding them. Trading can lose money, including everything you allocate, so every control exists to bound that downside.

How do you handle errors and retries in MCP trading workflows?

Trading over MCP is distributed and asynchronous. An agent calls a tool, the infrastructure routes it, and the market may accept, reject, or partially fill the order. Developers should design workflows that expect failure. Network timeouts, rate limits, and invalid parameters are common. Retries should be idempotent where possible. For example, querying a position is safe to retry. Submitting a market order is not, because each attempt could execute against a moving price. A better pattern is to submit once, receive an order ID, and poll for status. If the status is unknown after a timeout, the agent should check the position or open orders before deciding whether to send another request. Error messages from the API are normalized, but the agent's reasoning layer must interpret them correctly. An "insufficient margin" error should not trigger an immediate retry with a larger size. It should trigger a pause and a notification to the owner. Errors specific to a market include market closed, invalid symbol, or size below minimum. These errors should be surfaced to the agent as structured data so the LLM can reason about them. However, the developer should not assume the agent will always reason correctly. A fallback policy is necessary. If the agent receives three consecutive errors, the workflow should halt and notify the owner. Partial fills are another common edge case. An agent might request a two hundred dollar buy, receive a one hundred dollar fill, and leave the remainder open. The agent needs a policy for whether to leave the order working, cancel it, or resubmit. Resubmitting blindly can lead to overfilling. The safest default is to cancel the unfilled portion and reassess. Logging every tool call and response creates an audit trail. In an MCP context, this means the client logs plus the Felix logs should align. For critical errors, human escalation is the correct pattern. Autonomy is useful, but only within a boundary that knows when to stop.