ToolXiv
Sign in
All docs

MCP Server Guide

Connect your AI agent directly to ToolXiv via Model Context Protocol

What is MCP?

Model Context Protocol (MCP) is an open standard that lets AI agents call external tools directly. Instead of asking you to copy-paste API responses, your agent can search ToolXiv, look up tool details, and even submit new tools — all within the conversation.

The @toolxiv/mcp package gives your agent 6 tools to interact with the ToolXiv registry.

Quick Start

No installation required. Just add the config to your AI client and it runs via npx.

Claude Code

Run this command in your terminal:

claude mcp add toolxiv -- npx -y @toolxiv/mcp

Or add it manually to your settings file (~/.claude.json):

{
  "mcpServers": {
    "toolxiv": {
      "command": "npx",
      "args": ["-y", "@toolxiv/mcp"]
    }
  }
}

Claude Desktop

Open Settings → Developer → Edit Config and add:

{
  "mcpServers": {
    "toolxiv": {
      "command": "npx",
      "args": ["-y", "@toolxiv/mcp"]
    }
  }
}

Cursor

Open Settings → MCP Servers → Add Server and enter:

{
  "mcpServers": {
    "toolxiv": {
      "command": "npx",
      "args": ["-y", "@toolxiv/mcp"]
    }
  }
}

After adding the config, restart your client. You should see ToolXiv tools listed in the MCP panel.

Available Tools

search_tools

Search the ToolXiv registry with filters.

Parameters:

  • q — Search query (e.g. "web scraper", "code formatter")
  • categories — Comma-separated category slugs (e.g. "cli-tools,ai-ml")
  • language — Programming language (e.g. "Python", "Rust")
  • license — License filter (e.g. "MIT", "Apache-2.0")
  • agent — AI agent filter (e.g. "claude-code", "cursor")
  • sort — Sort by relevance, newest, stars, or impact
  • page — Page number

Example prompt:

Find Python CLI tools for web scraping, sorted by stars

get_tool

Get full details about a specific tool by its ID.

Parameters:

  • id — Tool ID (numeric)

Example prompt:

Get details for tool #42

get_trending

See what's popular right now on ToolXiv.

Parameters:

  • limit — Number of results, 1–50 (default: 10)

Example prompt:

Show me the top 5 trending tools

list_categories

List all available categories. Useful for discovering valid category slugs to use with search_tools.

No parameters. Returns:

  • cli-tools — CLI Tools
  • web-apps — Web Apps
  • dev-tools — Dev Tools
  • api-services — API & Services
  • data-tools — Data Tools
  • ai-ml — AI & ML
  • automation — Automation
  • libraries — Libraries & SDKs

get_user_profile

Look up a creator's public profile with citation metrics.

Parameters:

  • username — ToolXiv username

Example prompt:

Show me the profile and tools for user "johndoe"

submit_tool

Submit a new tool to ToolXiv. Requires an API key (see below).

Parameters:

  • name — Tool name
  • description — Short description (10–500 characters)
  • repositoryUrl — GitHub/GitLab URL
  • categories — Array of category slugs (1–3)
  • tags — Array of tags (up to 10)
  • longDescription — Detailed description (optional)
  • websiteUrl — Project website (optional)
  • language — Primary language (optional)
  • license — License identifier (optional)
  • agentPrompt — Agent integration prompt (optional)
  • citations — References to other tools (optional)

The submitted tool enters "pending" status and goes through review before appearing publicly.

Example prompt:

Submit my tool "fastparse" — a Rust CLI for parsing large CSV files.
Repository: https://github.com/me/fastparse
Categories: cli-tools, data-tools
Tags: csv, parser, rust, performance
License: MIT

Authentication

Reading is free. The first 5 tools (search_tools, get_tool, get_trending, list_categories, get_user_profile) work without any API key. Anonymous access is rate-limited to 100 requests/day and 10 requests/minute.

Submitting requires an API key. Generate one from your dashboard, then add the env block to your config:

{
  "mcpServers": {
    "toolxiv": {
      "command": "npx",
      "args": ["-y", "@toolxiv/mcp"],
      "env": {
        "TOOLXIV_API_KEY": "txv_your_key_here"
      }
    }
  }
}

With an API key, your rate limit increases to 1,000 requests/day with no per-minute burst limit.

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | TOOLXIV_API_KEY | Only for submit_tool | — | Your API key (starts with txv_) | | TOOLXIV_API_URL | No | https://toolxiv.org/api/v1 | Custom API URL (for development) |

Rate Limits

| Tier | Daily Limit | Burst Limit | How to Get | |------|-------------|-------------|------------| | Anonymous | 100/day | 10/min | No setup needed | | Authenticated | 1,000/day | None | Add TOOLXIV_API_KEY |

Rate limit headers are included in every API response:

  • X-RateLimit-Limit — Your daily limit
  • X-RateLimit-Remaining — Requests left today
  • X-RateLimit-Reset — When the limit resets (Unix timestamp)

Usage Examples

Discover tools for a project

I'm building a data pipeline in Python. Search ToolXiv for
relevant data tools and automation libraries I could use.

Research before building

Before I build a new markdown parser, search ToolXiv to see
if one already exists. Check trending tools too.

Submit after building

I just finished building my tool. Submit it to ToolXiv:
- Name: logpeek
- Description: A lightweight CLI for tailing and filtering structured logs
- Repo: https://github.com/me/logpeek
- Categories: cli-tools, dev-tools
- Tags: logging, cli, structured-logs, json
- Language: Go
- License: MIT

Troubleshooting

"User-Agent header is required"

The MCP server sets this automatically. If you see this error, you may be calling the API directly without a User-Agent header. Add one to your requests.

"TOOLXIV_API_KEY is required for this operation"

You're trying to use submit_tool without an API key. Add your key to the env block in your MCP config.

Tools not showing up in Claude Code

Run claude mcp list to verify the server is registered. If it's missing, re-add it:

claude mcp add toolxiv -- npx -y @toolxiv/mcp

Connection timeout

The server fetches data from toolxiv.org. Check your internet connection. For local development, set TOOLXIV_API_URL to your local server.

Next Steps

PreviousCreator Profiles