Marketplace MCP

The Marketplace MCP is a single Model Context Protocol endpoint that puts the entire Rival marketplace behind one connection. Point any MCP-compatible client at it with your API key, and the model can search for tools, read their input schemas, and run them - across every published Function, MCP server, and Storm classifier - without wiring up each tool individually.

Use it to plug Rival into Claude Code, Cursor, Gemini CLI, MCP inspectors, your own agents, or any platform that speaks MCP.

Endpoint

One Streamable-HTTP MCP endpoint serves everything:

https://cortexone-api.rival.io/api/v1/marketplace/mcp

It speaks standard MCP over HTTP (the Streamable HTTP transport), so any compliant MCP client can connect to it directly.

Authentication

Requests are authenticated with a Rival API key.

Create one at cortexone.rival.io/user/api-keys. Keys begin with RIV_ and are organization-wide - a single key can reach every tool your organization owns or has access to, plus all public marketplace tools.

Pass the key in the Authorization header on every request - no Bearer prefix, just the key:

Authorization: RIV_your_api_key_here

Most MCP clients let you attach this header when you add a custom server (see Connecting a client).

The tools

The gateway exposes a small, fixed set of meta-tools. The model uses them to discover and run anything in the marketplace - so tools/list stays small no matter how large the catalog grows.

Tool	What it does
`search_tools`	Search the marketplace and return matching tools (id, type, description, price, popularity).
`get_tool_schema`	Get a tool’s input schema (and a working example) before running it.
`invoke_tool`	Run a tool and return its result. Billed per run.
`check_balance`	Check your organization’s run balance.

The natural flow is search → get schema → invoke:

search_tools to find a tool that fits the task.
get_tool_schema to learn its exact inputs.
invoke_tool to run it and use the result.

Most MCP clients drive this loop automatically - you just ask in natural language (e.g. “read this web page and summarize it”) and the model searches, picks a tool, and runs it.

`search_tools`

Search the marketplace for published tools.

Arguments

Field	Type	Required	Description
`query`	string	yes	Keywords to search for.
`limit`	integer	no	Results per page (1-50, default 20).
`offset`	integer	no	Offset for pagination (default 0).
`free_only`	boolean	no	Only return tools that are free to run.
`verified_only`	boolean	no	Only return verified tools.

Returns a list of matches, each with tool_id, name, description, type (function / mcp / storm), latest_version, price_per_run, organization, runs, rating, and reviews - plus total, offset, limit, and next_offset for paging.

`get_tool_schema`

Get the input schema and metadata for one tool.

Arguments

Field	Type	Required	Description
`tool_id`	string	yes	The tool’s id, from `search_tools`.

Returns tool_id, name, type, latest_version, price_per_run, organization, and:

For Function and Storm tools: an input_schema (JSON Schema) plus an example_input you can copy.
For MCP tools: a list of sub_tools - pass the chosen one to invoke_tool.

`invoke_tool`

Run a tool and return its result. Each call is billed per run to your organization.

Arguments

Field	Type	Required	Description
`tool_id`	string	yes	The tool’s id.
`arguments`	object	yes	The tool’s inputs (see `get_tool_schema`).
`version`	string	no	A specific version to run. Defaults to the latest published version.
`sub_tool`	string	no	For MCP tools only: the sub-tool to call.

Returns the tool’s output.

`check_balance`

Return your organization’s current run balance - what you can spend running tools. No arguments. Useful before running paid tools.

Connecting a client

Any client that supports a remote (Streamable HTTP) MCP server with a custom header works. Set the URL to the endpoint and add the Authorization header with your RIV_ key.

Generic configuration

Most clients (Cursor, Windsurf, and others) use an mcpServers block:

{
  "mcpServers": {
    "rival-marketplace": {
      "url": "https://cortexone-api.rival.io/api/v1/marketplace/mcp",
      "headers": {
        "Authorization": "RIV_your_api_key_here"
      }
    }
  }
}

Claude Code

claude mcp add --transport http rival-marketplace \
  https://cortexone-api.rival.io/api/v1/marketplace/mcp \
  --header "Authorization: RIV_your_api_key_here"

Gemini CLI

{
  "mcpServers": {
    "rival-marketplace": {
      "httpUrl": "https://cortexone-api.rival.io/api/v1/marketplace/mcp",
      "headers": {
        "Authorization": "RIV_your_api_key_here"
      }
    }
  }
}

MCP inspectors

In tools like the MCP Inspector, add a server with Transport: Streamable HTTP, the endpoint URL, and an Authorization header set to your RIV_ key.

Once connected, the client lists the meta-tools above and you can search and run marketplace tools immediately.

Using it directly over HTTP

If you’re integrating without an MCP SDK, you can speak the protocol with plain HTTP requests. Every request is a JSON-RPC 2.0 message POSTed to the endpoint.

Initialize

curl https://cortexone-api.rival.io/api/v1/marketplace/mcp \
  -H "Authorization: RIV_your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": { "name": "my-app", "version": "1.0" }
    }
  }'

List the meta-tools

curl https://cortexone-api.rival.io/api/v1/marketplace/mcp \
  -H "Authorization: RIV_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }'

Search the marketplace

curl https://cortexone-api.rival.io/api/v1/marketplace/mcp \
  -H "Authorization: RIV_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "search_tools",
      "arguments": { "query": "web", "limit": 5 }
    }
  }'

Run a tool

curl https://cortexone-api.rival.io/api/v1/marketplace/mcp \
  -H "Authorization: RIV_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "invoke_tool",
      "arguments": {
        "tool_id": "d8299d85-d3e1-4f0b-8b75-2e3793b7bd8d",
        "arguments": { "url": "https://en.wikipedia.org/wiki/Artificial_intelligence" }
      }
    }
  }'

Tool results come back inside the JSON-RPC result.content array as text. For MCP-type tools, also pass sub_tool in arguments.

Pricing

Running a tool through the gateway costs the same as calling it directly: the tool’s per-run price, billed to your organization’s run balance. search_tools, get_tool_schema, and check_balance are free - only invoke_tool is charged, and only on success.

Top up your balance in Settings → Billing, and use check_balance to see what’s available before running paid tools.

What you can reach

The gateway exposes:

All public marketplace tools - every published Function, MCP server, and Storm classifier.
Your organization’s own tools - including private ones - when you connect with your organization’s API key.

It never exposes another organization’s private tools.

See Marketplace for browsing and discovery, Tool Types for the difference between Functions, MCP servers, and Storm, and APIs for calling a single tool directly over HTTP.

Errors

Errors come back as standard JSON-RPC error objects or, for tool-level problems, as a result with isError: true and a readable message. Common cases:

Situation	What you’ll see
Missing / invalid API key	`401 Unauthorized`
Unknown tool id	A tool result explaining the tool wasn’t found
Insufficient balance	A message to top up your run balance
Bad arguments	A message describing the missing or invalid input

For the full list of platform and runtime error codes, see the Error Reference.