Using AI Agents

The crowdcent-challenge package ships with a built-in Model Context Protocol (MCP) server, so AI assistants like Claude, Cursor, and Codex can work with the CrowdCent Challenge in natural language: download data, submit predictions, check performance, backtest portfolio constructions on the meta-model, and manage live trading (Challenger tier and above).

Setup

1. Get an API key. Create an account at crowdcent.com and generate a key in your profile settings.

2. Connect. There are two ways: the hosted server, which needs nothing installed, or a local server run with uvx.

Hosted (nothing to install)Local (one line, no clone)

Add https://mcp.crowdcent.com/mcp to any client that supports remote MCP servers over HTTP, using your API key as a bearer token.

Claude Code:

claude mcp add --transport http crowdcent https://mcp.crowdcent.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Cursor / VS Code (mcp.json):

{
  "mcpServers": {
    "crowdcent": {
      "url": "https://mcp.crowdcent.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

The hosted server is a stateless pass-through to the CrowdCent API: it stores nothing, and your key simply authenticates each request the same way the Python client does. Instead of writing files to disk, it hands your assistant signed download URLs (get_training_dataset_url, get_inference_data_url, get_meta_model_url), which agents with a terminal or fetch tool can use directly.

If you prefer running locally, or want the file-download and file-submission tools, configure your client with a single uvx command:

{
  "mcpServers": {
    "crowdcent": {
      "command": "uvx",
      "args": ["--from", "crowdcent-challenge[mcp]", "crowdcent-mcp"],
      "env": {"CROWDCENT_API_KEY": "your_api_key_here"}
    }
  }
}

That is the whole setup: no repository to clone, no absolute paths, and the server always matches the client library it ships with.

3. Say hello. Confirm the connection with a first ask:

"List the CrowdCent challenges and tell me about the current inference period."

What to ask

You don't need to know the tool names, just describe what you want. Some starting points, roughly in the order of a CrowdCent journey:

Explore the challenge

"What does the hyperliquid-ranking challenge involve, and what would I submit?"
"Show my recent submissions and how they scored."

Build and submit a model. Your assistant can run the whole loop: pull data, write and train a model in your workspace, and submit the predictions, all in one conversation.

"Download the latest CrowdCent training data, explore it, and train a
baseline ranking model. Predict the current inference period and show me
the predictions before submitting."

Coding agents like Claude Code and Cursor handle this end to end. Chat-only clients can still fetch data via the signed-URL tools and submit inline from a dataframe.

Backtest on the meta-model. The simulation tools answer "how would trading the community's aggregated signal have performed?" with the same engine, tier gates, and honesty stance as the site's Simulation tab. Sweep configurations, blend sleeves, and compare in-sample against out-of-sample.

"Backtest 10 long / 10 short equal weight on the meta-model, rebalanced
every 10 days with funding on, and give me the link to view it on the site."

"Sweep leg size 5/10/20 and cadence 1/5/10 days on the meta-model, and tell
me where the stable region is, in-sample and out."

"Blend a fast small-book sleeve with a slower HRP sleeve 60/40 and show the
combined out-of-sample stats and correlation."

The sweep tool's own guidance applies: read plateaus, not peaks. A lone bright cell is luck; a bright region is structure. Every result includes a web_url deep link, so anything your assistant finds can be opened and inspected on crowdcent.com.

Check in each morning (trading-enabled accounts):

"Give me my CrowdCent morning briefing."

Built-in workflows

The server ships two prompts, packaged versions of the asks above that encode the recommended workflow. In Claude Code they appear as slash commands (/mcp__crowdcent__sweep_and_summarize, /mcp__crowdcent__morning_briefing); other clients surface them in their prompt picker.

• sweep_and_summarize: runs a sweep, tables in-sample and out-of-sample Sharpe, identifies the stable plateau rather than the single best cell, recommends one configuration from inside it, and hands you the site deep link.
• morning_briefing: pulls your recent scores, account state, last rebalance results, and working orders, then narrates what needs your attention. Built for trading-enabled accounts; anyone can use it for the scoring summary.

CrowdCent Cloud

For Cloud-enabled keys, your assistant can create a CrowdCent Cloud project from a Cookbook recipe or source it wrote, edit saved files, run code on CrowdCent hardware, read reports, and check credits. It can schedule saved code directly for daily, weekly, monthly, inference-release, or after-success execution. No previous run is required; a successful run is an optional way to reuse tested settings.

The tools manage saved project files, Cloud Runs, schedules, and credit information. In local stdio mode, upload_cloud_project_files puts data files from your machine (a trained model, a parquet) into a project's folder, and download_cloud_project_file brings one back; the bytes go straight to storage, never through the assistant. Live editing in the Browser or a Cloud Session is available on the website. The tools use the same project API as the Python client; arguments and return shapes are detailed in the Python API reference.

For storage, get_cloud_billing reports usage and update_cloud_billing sets an explicit monthly cap for extra storage charges. It does not buy credits. update_cloud_project(prune_history=True) permanently removes eligible old outputs while preserving current files and saved code. Both require your explicit request; assistants should not raise caps or prune history just to make a save fit.

"Save optimize.py and predict.py in one project. Schedule optimization for
Monday at 02:00 UTC on M hardware and prediction after it succeeds, using
the saved model. Don't start a run now."

Cloud tools appear when your API key has Cloud enabled (Settings → "Allow Cloud"). Executing a run spends Cloud credits; creating a schedule starts no compute and reserves no credits. A schedule pins saved code and settings until you explicitly update it. Partial file edits require the version the edit started from, so stale edits return a conflict instead of overwriting newer work. Keep Cloud and live trading on separate keys; an agent editing notebooks should never hold a credential that can trade.

Live trading

For trading-enabled accounts, the same tools that power the site's Trading tab: inspect the mandate and target book, preview a rebalance, execute it after your explicit confirmation, flatten, pause, and read the run and order audit trail. The concepts (mandates, custody, the consent flow) are covered in Live Trading.

"Set the mandate to the sweep config we just picked, preview the rebalance
on testnet, and walk me through the plan before executing anything."

Trading tools appear when your API key has live trading enabled (Settings → "Allow live trading") and your account meets the eligibility requirements (Challenger tier with 100+ CC Points and an active submission in the last 30 days). That is the same locally and on the hosted server. Execution is always two-step: the assistant previews a plan, shows it to you, and needs the preview's plan_hash (valid for 10 minutes) to execute. Every cap and gate is enforced server-side, and custody never moves: agent keys are trade-only, never-withdraw, and stay encrypted on CrowdCent's side. The MCP server holds nothing but your API key.

Troubleshooting

• "API key not provided": set CROWDCENT_API_KEY in the server's env block (local) or the Authorization header (hosted).
• Trading tools missing: enable "Allow live trading" on your key in the trading tab. Trading requires Challenger tier (100+ CC Points) and an active submission in the last 30 days — without eligibility, tools stay hidden and API calls return 403.
• Cloud tools missing: enable "Allow Cloud" on your key in profile settings to expose the tools. Calls also require an eligible account: anyone with a Challenge submission.
• A knob didn't take effect: simulation knobs above your points tier are clamped to your tier, and the response's locked list names which ones. Error messages state the tier and points needed to unlock.
• Submission format: predictions need the challenge's required columns (for hyperliquid-ranking: id, pred_10d, pred_30d), and submissions are only open during the challenge's submission window.