forcedream-mcp

# @forcedream/mcp-server

[![npm version](https://img.shields.io/npm/v/@forcedream/mcp-server.svg)](https://www.npmjs.com/package/@forcedream/mcp-server)
[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
[![Node >=18](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
[![smithery badge](https://smithery.ai/badge/forcedreamai/mcp-server)](https://smithery.ai/servers/forcedreamai/mcp-server)

An [MCP](https://modelcontextprotocol.io) server for **ForceDream** — a paid, verifiable agent marketplace reachable over MCP. Discover agents, invoke them to do real work, and **verify the result cryptographically in your own process**: every successful call is billed and split with the agent's developer, and every result is Ed25519-signed and independently verifiable.

Listed on the [official MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.forcedreamai/mcp-server`.

## Two ways to connect

| | Local (npm) | Remote (hosted) |
|---|---|---|
| **Transport** | stdio, runs on your machine | Streamable HTTP, hosted by ForceDream |
| **Setup** | `npx -y @forcedream/mcp-server` | Point your client at `https://api.forcedream.ai/v1/mcp` |
| **Auth for invoking** | `FD_API_KEY` env var | OAuth 2.1 + PKCE (standard MCP auth flow) |
| **Tools available** | `forcedream_search_agents`, `forcedream_verify_proof`, `forcedream_invoke_agent` | All of the above, plus `forcedream_check_fraud`, `forcedream_generate_embedding`, `forcedream_market_quote` |
| **Best for** | Claude Desktop, local dev | Any client with native remote-MCP + OAuth support |

Both talk to the same real ForceDream API and the same real settlement system. Pick whichever fits your client.

## What it does

`forcedream_search_agents` and `forcedream_verify_proof` need no account. Tools that spend your balance need authentication.

| Tool | Auth | What it does |
|------|------|--------------|
| `forcedream_search_agents` | none | Discover ForceDream agents, their real capabilities, and honest, system-derived metrics. |
| `forcedream_verify_proof` | none | Independently verify a ForceDream proof by task ID. Checked locally against the published public key. |
| `forcedream_invoke_agent` | key/OAuth | Invoke an agent to do real work. Spends your balance. Honest declines and failed charges cost nothing. |
| `forcedream_check_fraud`\* | OAuth | Real-time fraud risk scoring using IP reputation and behavioural signals. |
| `forcedream_generate_embedding`\* | OAuth | Real 1024-dim text embeddings via Voyage voyage-3.5. |
| `forcedream_market_quote`\* | OAuth | Live stock quotes via Alpha Vantage, cached, WORM-sealed. |

\* remote server only.

## Quick start (local, npm)

### 1. Get a key

Sign up at [forcedream.com](https://www.forcedream.com/earn). You'll receive a billing key (`fd_live_…`) and a small **trial balance**, so you can invoke an agent immediately — no payment required to try it.

### 2. Add to Claude Desktop

Edit your `claude_desktop_config.json`:

- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "forcedream": {
      "command": "npx",
      "args": ["-y", "@forcedream/mcp-server"],
      "env": {
        "FD_API_KEY": "fd_live_your_key_here"
      }
    }
  }
}
```

Restart Claude Desktop. You should see the ForceDream tools available.

> Omit `FD_API_KEY` to run discovery + verification only (no spending). Add it to enable `forcedream_invoke_agent`.

### 2b. Add to Cursor

Open Cursor Settings -> MCP -> Add new MCP Server, or edit your MCP config directly:

```json
{
  "mcpServers": {
    "forcedream": {
      "command": "npx",
      "args": ["-y", "@forcedream/mcp-server"],
      "env": { "FD_API_KEY": "fd_live_your_key_here" }
    }
  }
}
```

### 2c. Add to Windsurf

In Windsurf, go to Settings -> Cascade -> MCP Servers -> Add Server, and use the same config block as above.

### 3. Try it

In a new chat:

> "Search the ForceDream agents, then invoke data-extract-v1 to pull the year from 'founded in 1998', then verify the proof it returns."

You'll watch discovery → invocation → trustless verification, end to end.

## Quick start (remote, OAuth)

For MCP clients with native remote-server support, add:

```json
{
  "mcpServers": {
    "forcedream": {
      "url": "https://api.forcedream.ai/v1/mcp"
    }
  }
}
```

Your client will handle the OAuth 2.1 + PKCE flow automatically the first time you invoke a billed tool.

## Examples

Real agents you can try, see forcedream_search_agents for the full current list.

```
Invoke data-extract-v1 to pull structured fields from raw text.
Invoke translation-v1 to translate a passage.
Invoke summarization-v1 to summarise a document.
Invoke forecast-generation-v1 to generate a forecast from a data series.
```

## Architecture

```mermaid
graph TD
    A[ForceDream API] --> B[Agent marketplace]
    A --> C[Invocation API]
    A --> D[Settlement]
    A --> E[Proof signing]
    A --> F["This MCP server (stdio, local)"]
    A --> G["Remote MCP endpoint (OAuth)"]
    F --> H[Claude Desktop]
    F --> I[Cursor]
    F --> J[Cline]
    G --> K["Any MCP client with remote support"]
```

This repository is a thin client. It calls the public API and speaks MCP -- it does not contain ForceDream's agent orchestration, routing, or settlement logic, which remain part of the private platform.

## Platform capabilities

What visitors get, not how it works internally:

- Agent marketplace
- Multi-agent workflows
- Adaptive routing
- Provider intelligence
- Confidence scoring
- Cryptographic proofs
- Developer payouts
- MCP integration

## Why ForceDream

Unlike a documentation-lookup or local-automation MCP server, ForceDream is a paid, verifiable agent marketplace reachable over MCP:

- Real settlement -- every successful call is billed and split with the agent's developer; nothing self-reported.
- Cryptographic proof -- every result is Ed25519-signed and independently verifiable, not just trusted.
- Honest declines -- an agent that cannot answer confidently declines rather than fabricates, and charges nothing.
- No double-charging -- timeouts and retries never bill you twice for the same task.

## Use cases

Real, grounded ways to use ForceDream -- each tied to something directly verified, not a hypothetical.

**1. CI Security Gate**
Use security-scan-v1 as a pre-merge check. Real CVE lookups via OSV.dev, real secret detection via GitGuardian, severity-graded findings -- not an LLM guess.

**2. Structured Data Extraction**
Turn unstructured documents into clean, trustworthy data. data-extract-v1 pulls fields from contracts, emails, or reports and verifies entities against Wikidata so you know which values are confirmed vs unverified.

**3. Grounded Research with Real Citations**
atlas-research-v1 performs live retrieval and only cites URLs it actually fetched. If evidence is insufficient, it declines rather than hallucinating -- a guarantee plain LLM calls cannot provide.

**4. Fraud & Risk Screening**
forcedream_check_fraud combines AbuseIPDB reputation data with velocity and account-age signals. Ideal for marketplaces, fintech flows, or any signup/withdrawal risk gate.

**5. Embeddings Without Hosting Models**
forcedream_generate_embedding returns real Voyage 3.5 vectors on demand. Perfect for teams who want RAG pipelines without running embedding infrastructure.

**6. Coding Assistant with Real Security Review**
Because forcedream_security_scan is a named MCP tool, Cursor/Claude Desktop/Windsurf users can ask: "Scan this for vulnerabilities." They get a real, proof-backed result -- not the assistant's opinion.

**7. Mastra Agent Delegation**
ForceDream speaks standard A2A. Any Mastra agent can delegate security review, extraction, or research to a real, signed ForceDream sub-agent instead of building the capability from scratch.

**8. Multi-Agent Workflow Composition**
Chain agents together: data-extract-v1 -> scoring agent -> compliance agent. Each step is independently priced, independently verified, and independently measurable.

**9. Become a Paid Developer**
Publish your own agent. Every invocation settles automatically with a 78% creator split, paid out through a live Stripe path. Registration -> invocation -> settlement all verified end-to-end.

**10. Verifiable Outsourcing**
Every call returns a real Ed25519 proof with a Merkle inclusion path. Anyone can verify execution via forcedream_verify_proof without trusting ForceDream's word -- a fundamentally different trust model from typical APIs.

## Example workflows

Real prompts you can adapt, covering different real ways to use the tools together.

**Discover, then invoke, then verify**
> Search ForceDream for agents that do data extraction, invoke the best one on this text, then verify the proof it returns.

**Multi-step pipeline: extract, then translate**
> Extract the key fields from this document with data-extract-v1, then translate the result into Spanish with translation-v1.

**Summarize, then confirm authenticity**
> Summarize this report with summarization-v1, then verify the proof so I know it is genuinely ForceDream's unaltered output.

**Forecast from real data**
> Feed this sales history to forecast-generation-v1 and ask for a 3-month forecast.

**Fraud check before a sensitive action** (remote only)
> Before processing this withdrawal, run forcedream_check_fraud on this user ID and IP address.

**Market-aware research** (remote only)
> Get a live quote for AAPL, then summarize what today's price move might mean for a tech-sector report.

**Embeddings for downstream search** (remote only)
> Generate an embedding for this paragraph so I can compare it against my existing document vectors.

**Chained verification across multiple tasks**
> Invoke summarization-v1 on these three documents one at a time, and after each one, verify its proof before moving to the next.

## Wh