@scopeful/mcp

STDIO MCP proxy that connects MCP-native agents (Claude Desktop, Claude Code, Cursor, Windsurf, Antigravity, Cline, Continue) to the Scopeful pricing engine.

The proxy speaks MCP locally on stdin/stdout, forwards tool calls to https://www.scopeful.org/api/mcp over HTTPS, and ships back the responses. No mcp-remote, no path issues, no npx gymnastics.

For terminal/subprocess use, install @scopeful/cli instead. Both packages hit the same endpoint, use the same key, and are tracked identically.

Install + configure

npm install -g @scopeful/mcp

The postinstall hook prints a paste-ready snippet for your AI agent to configure itself. Read it after install.

Generate an API key at https://scopeful.org/pro/api, then set it in the environment for the agent that will spawn the proxy.

Claude Code / Claude Desktop

Add to claude_desktop_config.json (or .mcp.json for Claude Code):

{
  "mcpServers": {
    "scopeful": {
      "command": "npx",
      "args": ["-y", "@scopeful/mcp"],
      "env": {
        "SCOPEFUL_API_KEY": "sk_mcp_your_api_key_here"
      }
    }
  }
}

Cursor

Settings > Features > MCP > + Add New MCP Server:

• Name: scopeful
• Type: command
• Command: npx -y @scopeful/mcp
• Env: SCOPEFUL_API_KEY=sk_mcp_your_api_key_here

Windsurf / OpenCode / other MCP clients

Add the same scopeful server block under mcpServers in your client's workspace or global config.

What you get

The proxy exposes whatever tools the Scopeful MCP server advertises at startup — currently 8 tools for deterministic cost calculation, discovery, skill delivery, and workflow retrieval:

| Tool | Use it for | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | recommend_tool | Start here for discovery. Ranked tool+model+plan combos with cost rationale + integration-skill pointers. | | get_skill | Universal skill delivery. Returns the full SKILL.md playbook for a tool by slug. No install required, works for every MCP client. | | calculate_pricing | Exact cost for a named model + volume + access. | | compare_tools | Side-by-side ranking of 2-3 named tools. | | list_tools | Catalog enumeration, filterable by category. | | list_models | Canonical model catalog, filterable by type/kind/provider. | | get_tool | Full pricing structure for one tool (plans, models, bundles); also returns the tool's integration_skills array. | | retrieve_workflow | Fuzzy-searches vetted multi-step workflows. Pro subscribers only. | | team_workflows | Search the caller's team-scoped workflow templates. Requires a team-scoped API key. | | get_usage | Return the caller's MCP usage for the current calendar month. Personal + team (when team-scoped). |

Every response carries meta.staleness_days — surface it to the user when it matters.

Install the agent skill (optional)

scopeful-mcp setup

Drops the scopeful skill into ~/.agents/skills/, ~/.claude/skills/, and ~/.cursor/skills/. Restart your agent to pick it up.

Environment variables

| Variable | Required | Default | Notes | | ------------------ | -------- | ---------------------------------- | -------------------------------------------------------------------------------------------------- | | SCOPEFUL_API_KEY | Yes | — | Bearer token for https://www.scopeful.org/api/mcp. Create one at https://scopeful.org/pro/api. | | SCOPEFUL_MCP_URL | No | https://www.scopeful.org/api/mcp | Override the upstream endpoint. Useful for local development against a mock server. |

Requirements

• Node.js >=18 (declared in engines).
• An MCP client capable of spawning the proxy and speaking JSON-RPC over stdio.

License

MIT