MCP Server Reference

Quick setup: Most users should use the hosted remote server. Add it to Claude.ai, Claude Cowork, or Claude Code, authentication is via OAuth. The reference below applies to both the remote and local MCP servers.

The everyrow MCP server enables deployment of a team of researchers to forecast, score, rank, or gather data. These tools are called directly by Claude Code, Claude.ai, and other MCP clients, no Python code is needed.

All operations use an async pattern: submit the task, poll for progress, then retrieve results. This allows long-running operations (1-10+ minutes) to work reliably with MCP clients.

Setup

Claude.ai and Claude Desktop

1. Go to Settings → Connectors → Add custom connector and enter the remote MCP URL:

https://mcp.futuresearch.ai/mcp

2. (Optional but recommended) Whitelist the everyrow upload URL so Claude can upload datasets straight from its sandbox — the data doesn't need to pass through the conversation context, saving tokens and improving reliability:

   Settings → Capabilities → Code execution and file creation → Additional allowed domains → add mcp.futuresearch.ai

Claude Code

Option A: Plugin install (recommended)

claude plugin marketplace add futuresearch/everyrow-sdk
claude plugin install everyrow@futuresearch

Option B: Remote HTTP MCP

claude mcp add futuresearch --scope project --transport http https://mcp.futuresearch.ai/mcp

Then start Claude Code and authenticate:

1. Run claude
2. Type \mcp, select everyrow, and complete the OAuth flow
3. Test with: "check my everyrow balance"

Authentication

Remote MCP (Claude.ai, Claude Desktop, Claude Code HTTP): OAuth 2.0 via Google. Authentication is handled automatically by the MCP client — no API keys or manual setup required. You'll be prompted to sign in with your Google account on first use.

Claude Code plugin (stdio): Uses an API key. Generate yours at futuresearch.ai/api-key and paste it when prompted during plugin setup.

Operation Tools

everyrow_browse_lists

Browse available reference lists of well-known entities — companies (S&P 500, FTSE 100, Russell 3000, sector breakdowns), geographic lists (countries, US states, cities), people (billionaires, heads of state), institutions (universities, regulators), and more.

Call with no parameters to see all available lists, or narrow results with search/category. Returns names, fields, and artifact_ids to pass to everyrow_use_list.

everyrow_use_list

Import a reference list into your session and save it as a CSV file. The copy is a fast database operation (<1s) — no polling needed.

Returns the saved CSV path, row count, and column names.

everyrow_screen

Filter rows in a CSV based on criteria that require judgment.

Returns task_id and session_url. Call everyrow_progress to monitor.

everyrow_rank

Score and sort rows by qualitative criteria.

Returns task_id and session_url. Call everyrow_progress to monitor.

everyrow_dedupe

Remove semantic duplicates.

Returns task_id and session_url. Call everyrow_progress to monitor.

everyrow_merge

Join two CSVs using intelligent entity matching (LEFT JOIN semantics).

Returns task_id and session_url. Call everyrow_progress to monitor.

everyrow_classify

Classify each row into one of the provided categories.

Returns task_id and session_url. Call everyrow_progress to monitor.

everyrow_forecast

Forecast the probability of binary questions. The input CSV should contain a question column. Recommended additional columns: resolution_criteria, resolution_date, background.

Output columns added: probability (int, 0–100) and rationale (string).

Returns task_id and session_url. Call everyrow_progress to monitor.

everyrow_agent

Run web research agents on each row.

Returns task_id and session_url. Call everyrow_progress to monitor.

everyrow_single_agent

Run a single web research agent on a question, without a CSV. Use this when you want to research one thing — the agent can search the web, read pages, and return structured results.

Returns task_id and session_url. Call everyrow_progress to monitor.

Progress and Results Tools

everyrow_progress

Check progress of a running task. Blocks for a few seconds before returning.

Returns status text with completion counts and elapsed time. Instructs the agent to call again immediately until the task completes or fails.

everyrow_results

Retrieve results from a completed task and save to CSV.

Returns confirmation with row count and file path.

everyrow_cancel

Cancel a running task. Use when the user wants to stop a task that is currently processing.

Returns a confirmation message. If the task has already finished, returns an error with its current state.

everyrow_list_sessions

List all sessions owned by the authenticated user. Returns session names, IDs, timestamps, and dashboard URLs. No parameters required.

Returns a formatted list of sessions with links to the web dashboard.

everyrow_list_session_tasks

List all tasks within a specific session. Returns task IDs, types, statuses, and timestamps.

Returns a formatted list of tasks in the session with their current status.

everyrow_upload_data

Upload data from a URL or local file. Returns an artifact_id for use in processing tools.

Use this to ingest data before calling any operation tool. Supported sources:

• HTTP(S) URLs (including Google Sheets — auto-converted to CSV export)
• Local CSV file paths (stdio/local mode only — not available over HTTP)

Returns artifact_id (UUID), session_id, row count, and column names.

everyrow_request_upload_url

Request a presigned URL to upload a local CSV file. This is the recommended way to ingest local files when using the remote HTTP MCP server.

Returns a presigned upload URL, upload ID, expiration time, max file size, and a ready-to-execute curl command. After uploading, use the returned artifact_id in any processing tool.

everyrow_balance

Check the current billing balance for the authenticated user. No parameters required.

Returns the account balance in dollars.

Workflow

1. everyrow_agent(task, input_csv)
   → Returns task_id + session_url (~0.6s)

2. everyrow_progress(task_id)
   → Blocks 12s, returns "Running: 5/50 complete, 8 running (15s elapsed)"
   → Response says "call everyrow_progress again immediately"

3. everyrow_progress(task_id)  (repeat)
   → "Running: 23/50 complete, 5 running (45s elapsed)"

4. everyrow_progress(task_id)  (final)
   → "Completed: 49 succeeded, 1 failed (142s total)"

5. everyrow_results(task_id, output_path)
   → "Saved 50 rows to /path/to/agent_companies.csv"

The agent handles this loop automatically. You don't need to intervene.

Usage Examples

Lead screening

"Screen this list and keep only companies with >50 employees that raised Series A+"

Uses everyrow_screen to filter a CSV of companies. Each row is evaluated by a web research agent that checks employee count and funding stage. Rows that don't meet the criteria are filtered out.

Web research

"For each competitor, find their pricing model, employee count, and latest funding"

Uses everyrow_agent with a custom response_schema to extract structured fields for each row. The agent searches the web for each company and returns the requested data.

Deduplication

"Dedupe this CRM export — merge rows referring to the same person"

Uses everyrow_dedupe to identify and remove semantic duplicates. Rows are compared beyond exact string matching — the agent recognizes that "J. Smith at Acme" and "John Smith, Acme Corp" are the same person.

Ranking

"Rank these nonprofits by climate impact in Sub-Saharan Africa"

Uses everyrow_rank to score and sort rows by a qualitative criterion. Each row is researched and scored, then the results are sorted.

Custom Response Schemas

All tools that accept response_schema take a JSON schema object:

{
  "type": "object",
  "properties": {
    "annual_revenue": {
      "type": "integer",
      "description": "Annual revenue in USD"
    },
    "employee_count": {
      "type": "integer",
      "description": "Number of employees"
    }
  },
  "required": ["annual_revenue"]
}

The top-level type must be object, and the properties must be non-empty. The valid field types are: string, integer, number, boolean, array, object.

Plugin

The Claude Code plugin (.claude-plugin/plugin.json) bundles:

1. MCP server, with all tools above
2. Skill, to guide agents with quick SDK code generation for the Python SDK path

Install with:

claude mcp add futuresearch --scope project --transport http https://mcp.futuresearch.ai/mcp

Troubleshooting

Auth flow not completing

If the OAuth sign-in window opens but authentication doesn't complete:

• Ensure pop-ups are not blocked in your browser
• Try closing and reopening the MCP connection
• For Claude Code HTTP mode, run \mcp and re-authenticate from the MCP panel

Task stuck in progress

If everyrow_progress keeps returning a running state for an extended period:

• Large datasets (1000+ rows) can take 10+ minutes — this is normal
• Use everyrow_cancel to stop the task and retry with a smaller dataset
• Check the session dashboard at the session_url for real-time status

Results appear empty

If everyrow_results returns fewer rows than expected:

• Some rows may have failed processing — check the session dashboard for error details
• Ensure the input CSV was well-formed (proper headers, no encoding issues)
• Retry failed rows by running the same operation on the filtered subset

Token budget exceeded

If you get a token budget error:

• Results are automatically paginated — call everyrow_results again to get the next page
• Use a custom response_schema with fewer fields to reduce output size
• Split large datasets into smaller batches

Privacy & Support

• Privacy Policy: futuresearch.ai/privacy
• Terms of Service: futuresearch.ai/terms
• Support: support@futuresearch.ai