onesource-docs-mcp

Give your AI assistant full access to the OneSource Web3 API documentation — search docs, explore the GraphQL schema, and find working query examples for Ethereum, Base, Optimism, Avalanche, Sepolia, and Shape.

What is MCP? The Model Context Protocol lets AI assistants call tools and access data sources. This server exposes OneSource documentation as 10 read-only tools — no API key or authentication needed.

Quick Start

Remote (zero setup)

Point any MCP client at the hosted endpoint — no install required:

https://docs.onesource.io/api/mcp

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "onesource-docs": {
      "command": "npx",
      "args": ["-y", "onesource-docs-mcp"]
    }
  }
}

Claude Code

claude mcp add onesource-docs -- npx onesource-docs-mcp

Any MCP Client (stdio)

npx onesource-docs-mcp

HTTP Server (self-hosted)

npx onesource-docs-mcp --http
npx onesource-docs-mcp --http --port=8080

Then connect your MCP client to http://localhost:3001/mcp.

Tools

| Tool | Purpose | When to use | |------|---------|-------------| | search_docs | Keyword search across all documentation | Finding guides, concepts, or API patterns | | get_query_reference | Full reference for a root GraphQL query | Building a specific query with correct args/filters | | get_type_definition | Schema definition for any type/enum/input | Understanding field shapes and return types | | list_examples | Browse or search working GraphQL examples | Finding ready-to-use query patterns | | list_supported_chains | All supported blockchain networks + endpoints | First question: "What chains are supported?" | | get_filter_reference | Filter fields and operators for a list query | Building filtered queries with correct syntax | | get_pagination_guide | Cursor-based pagination pattern with examples | Implementing pagination for list queries | | get_schema_overview | High-level summary of the entire schema | Exploring the API surface before diving in | | get_authentication_guide | API key format, headers, and endpoints | Setting up authentication for the first time |

search_docs

Search all OneSource documentation by keyword. Returns the top 5 matching sections with relevance scores.

{ "query": "NFT metadata" }

get_query_reference

Get the full reference for a root GraphQL query — arguments, filters, and return type.

Available queries: address, addresses, block, blocks, contract, contracts, nft, nfts, token, tokens, transaction, transactions.

{ "query_name": "transactions" }

Example output:

# transactions

Query transactions with filtering and pagination.

Returns: [Transaction] (non-null)

Arguments:
  - `filter`: `TransactionFilter` — Filter criteria for transactions
  - `first`: `Int` = 10 — Number of results to return
  - `after`: `String` — Cursor for pagination
  ...

get_type_definition

Get the schema definition for any GraphQL type, enum, scalar, input, or interface.

{ "type_name": "Transaction" }

list_examples

List all available examples, or search by topic. Without a topic, returns a summary listing of all examples. With a topic, returns full example content matching that keyword.

{ "topic": "token transfers" }

Call with no arguments to browse all available examples:

{}

list_supported_chains

List all blockchain networks supported by OneSource with endpoint URLs and chain slugs.

{}

get_filter_reference

Get all filter fields and range operators for a specific list query.

{ "query_name": "transactions" }

get_pagination_guide

Get the cursor-based pagination pattern with step-by-step flow and common mistakes. Optionally pass a query name.

{ "query_name": "tokens" }

get_schema_overview

Get a high-level summary of the entire GraphQL schema — all queries, types, enums, interfaces, and scalars at a glance.

{}

get_authentication_guide

Get the full authentication guide — API key format, endpoint pattern, required headers, and common mistakes.

{}

Troubleshooting

Tools return "Data files may be missing" The data/ directory wasn't included in the install. Try npm install onesource-docs-mcp again, or if developing locally, run npm run build:plugin from the repo root.

npx onesource-docs-mcp hangs with no output That's normal — stdio mode waits for JSON-RPC input on stdin. Use --http if you want an HTTP server you can curl.

Port already in use Another process is using port 3001. Specify a different port: npx onesource-docs-mcp --http --port=8080

"Type not found" even though it exists Type names are case-insensitive but must match the GraphQL name (e.g. Transaction, not transaction_type). The tool will suggest close matches if it can't find an exact match.

What's New in v2

• Factory pattern — single createMcpServer() entry point shared across stdio, HTTP, CLI, and Vercel
• HTTP transport — run as a standalone HTTP server with --http flag
• CLI entry point — npx onesource-docs-mcp just works, with --port support
• Remote endpoint — hosted at https://docs.onesource.io/api/mcp (zero setup)
• Pre-built data — schema and docs are bundled in the package, no build step needed after install

About

Maintainer: BlockParty Repository: 1s-developer-docs Security: All tools are read-only — no authentication, no writes, no API keys required.

Development

# From repo root
npm run build:plugin    # Build everything (skills + schema data + MCP server)
npm run build:mcp       # Build MCP server only

# Test locally
node scripts/mcp-server/dist/server.js        # stdio (dev mode)
node scripts/mcp-server/dist/http-server.js   # HTTP on :3001

License

MIT