FOR AI

Cosmopedia
for AI Agents

Machine-readable access to the Cosmos stack knowledge base.Cosmopedia exposes all content via MCP (Model Context Protocol) and a REST API. No authentication required.

Connect Cosmopedia in 4 steps

1Pick your AI tool

Config location: Your MCP client · docs ↗

2Paste this into your config

https://cosmopedia.xyz/mcp

3Test the connection

4Try these first

How does an IBC packet timeout work?
Conceptual semantic search over docs and forum
What did the forum discuss about removing the ICS provider module?
Keyword search over forum threads
What is the latest gaia release?
Reads github_releases for one named repository
Search GitHub issues about BlockSTM
Full-text search over indexed issues

Interactive API reference →

MCP Server

ENDPOINThttps://cosmopedia.xyz/mcp

Install in your IDE / editor (11)

▸Claude Desktopjson

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) · %APPDATA%\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "cosmopedia": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://cosmopedia.xyz/mcp"]
    }
  }
}

Claude Desktop expects stdio, not HTTP. mcp-remote bridges the two. A bare "type": "http" entry can silently drop your whole mcpServers block on startup.

▸Claude.ai (web/mobile)shell

Customize → Connectors → Add custom connector

URL: https://cosmopedia.xyz/mcp
Auth: none
Available on Free, Pro, Max, Team and Enterprise plans. Free is limited to one custom connector total.

▸Claude Code CLIshell

one-liner

claude mcp add --transport http cosmopedia --scope user https://cosmopedia.xyz/mcp

Drop --scope user for the default (local, current project only), or use --scope project to share via .mcp.json.

▸Cursorjson

~/.cursor/mcp.json (global) or .cursor/mcp.json (project)

{
  "mcpServers": {
    "cosmopedia": {
      "url": "https://cosmopedia.xyz/mcp"
    }
  }
}

▸Windsurfjson

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "cosmopedia": {
      "serverUrl": "https://cosmopedia.xyz/mcp"
    }
  }
}

The field is serverUrl, not url. Windsurf and Cursor use different names for the same thing.

▸VS Code (Copilot Agent Mode)json

.vscode/mcp.json (workspace) or user profile

{
  "servers": {
    "cosmopedia": {
      "type": "http",
      "url": "https://cosmopedia.xyz/mcp"
    }
  }
}

▸Cline (VS Code extension)json

MCP Servers panel → Remote Servers → Streamable HTTP

{
  "mcpServers": {
    "cosmopedia": {
      "type": "streamableHttp",
      "url": "https://cosmopedia.xyz/mcp",
      "disabled": false,
      "autoApprove": []
    }
  }
}

The type field matters here: without it Cline falls back to the legacy SSE transport instead of HTTP.

▸Continue.devyaml

.continue/mcpServers/cosmopedia.yaml (agent mode)

name: Cosmopedia
version: 0.0.1
schema: v1
mcpServers:
  - name: Cosmopedia
    type: streamable-http
    url: https://cosmopedia.xyz/mcp

▸Zedjson

settings.json → context_servers

{
  "context_servers": {
    "cosmopedia": {
      "url": "https://cosmopedia.xyz/mcp"
    }
  }
}

▸JetBrains (IntelliJ / PyCharm / WebStorm 2025.2+)shell

Settings → Tools → AI Assistant → Model Context Protocol → Add server

URL: https://cosmopedia.xyz/mcp
Transport: HTTP
Auth: none

▸ChatGPT (Plus / Pro / Team / Enterprise / Edu)shell

Settings → Connectors → Advanced settings → enable Developer mode, then Connectors → Create

URL: https://cosmopedia.xyz/mcp
Transport: Streamable HTTP
Auth: none
Read-only tools auto-allowed; the server has no write tools.

Available tools (33)

searchKeyword/full-text search over the Cosmopedia Cosmos knowledge base (forum, docs, GitHub, releases, security advisorie…

get_discussionGet a single thread from the Cosmos Hub community forum (forum.cosmos.network, Discourse) by numeric topic id: title,…

get_whitepaperGet one Cosmos stack whitepaper THIS SERVER has indexed, by slug: title, tag, a link to the original and its body tex…

list_whitepapersList every whitepaper indexed by Cosmopedia: slug, title, description, tag and page count (metadata only, no body)

get_trendingGet this week's most popular content in the Cosmopedia index (forum threads, docs, blog and more) ranked by an engage…

get_docFetch the FULL text of one indexed documentation page by its numeric id

list_reposList the GitHub repositories Cosmopedia has indexed, with the count of issues and PRs indexed per repo

list_github_discussionsList GitHub Discussions from the repositories cached by Cosmopedia, newest first

get_github_discussionGet the body and comments of a single GitHub Discussion by its GitHub GraphQL node id (from list_github_discussions)

get_videoGet a video that Cosmopedia has cached by its YouTube id: title, channel, publish date, description and an excerpt of…

list_videosList videos cached in Cosmopedia, filtered by channel, publish date (since) and transcript availability

semantic_searchPRIMARY tool for open-ended questions: how / why / what-is, troubleshooting a symptom, and locating configuration or…

search_github_issuesFull-text search across Cosmopedia's indexed GitHub issues

get_latest_releaseGet the latest release (version tag, publish date and release-notes link) for ONE NAMED indexed repository or package

search_release_notesSearch the release notes of the Cosmos stack repositories THIS SERVER has indexed (Hub, SDK, CometBFT, IBC, CosmWasm,…

hub_chain_stateCurrent Cosmos Hub chain state read from an LCD: block height and time, the scheduled upgrade plan, the version a nod…

list_proposalsList Cosmos Hub governance proposals from chain state, newest first: status, outcome, kind, voting end and vote shares

get_proposalGet one Cosmos Hub governance proposal by its on-chain id: status and outcome, timeline, deposit, vote shares, what i…

hub_upgradesCosmos Hub software-upgrade timeline: each upgrade proposal with the upgrade name and height, whether it has been app…

chain_upgradesUpcoming software upgrades announced for Cosmos chains other than, and including, the Hub, from a third-party feed (P…

list_chainsList Cosmos chains from the community chain-registry: chain id, address prefix, daemon, recommended version and how m…

get_chainGet one chain from the community chain-registry by name or chain id: address prefix, daemon and home, the codebase an…

ibc_channelsIBC channels of a chain from the community chain-registry: for each, the channel ids and ports on both sides, orderin…

search_advisoriesSearch security advisories for the Cosmos stack: Cosmos SDK, CometBFT, ibc-go, Gaia, Cosmos EVM and wasmd (ASA, ISA a…

get_advisoryGet one security advisory by id ("ASA-2025-004", "ISA-2025-004", "CWA-2025-001" or a GHSA id): severity, repository,…

search_specsSearch design documents of the Cosmos stack by status: Cosmos SDK ADRs and RFCs, CometBFT ADRs and RFCs, Gaia ADRs an…

get_specGet one ADR, RFC or ICS standard by label ("ADR-065", "RFC-100", "ICS-004"): status, dates, authors, ICS category and…

list_incidentsList post-mortems and incident reports for the Cosmos stack, newest first: the cosmos/incidents repository (Hub, IBC…

list_auditsList security audit reports for the Cosmos stack, newest named date first: the Cosmos SDK, Gaia liquid staking, Cosmo…

what_changedWhat changed in the Cosmos stack recently, newest first, across sources: GitHub releases of the SDK, CometBFT, ibc-go…

list_validatorsList validators of a Cosmos chain from cosmos.directory: rank, moniker, commission, missed blocks, jailed and active…

get_validatorGet one validator by operator address or exact moniker: rank, status, commission and its ceilings, missed blocks, RES…

data_sourcesList what this index is built from and how fresh each source is: for every source its category, precedence (1 chain s…

Troubleshooting

▸Tools don’t show up after adding the server

Claude Code: run /mcp in a session, or claude mcp list to check connection status. VS Code: run "MCP: List Servers" from the command palette to see logs. Cursor / Claude Desktop / Windsurf / Zed: fully quit and reopen the app. Closing the window is not enough.

▸Claude Desktop config file looks empty after restart

A bare {"type":"http","url":...} entry can cause Claude Desktop to silently drop the whole mcpServers block. Use the mcp-remote bridge form shown above instead, and keep a backup of claude_desktop_config.json before editing it by hand.

▸Getting 429 Too Many Requests

Check the RateLimit-* response headers for your remaining quota and the Retry-After header for how long to wait. Limits are per IP (see Rate limits below), not per API key. There is no key to upgrade.

▸Not sure if it’s a client problem or the server is down

Test the server directly, outside any client: curl -s https://cosmopedia.xyz/mcp -H "content-type: application/json" -H "accept: application/json, text/event-stream" -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | head -c 200. If that returns JSON starting with {"jsonrpc":"2.0", the server is fine and the issue is in your client config.

REST API v1

BASE URLhttps://cosmopedia.xyz/api/v1

Quick examples

curl https://cosmopedia.xyz/api/v1/search?q=ibc&limit=5
curl https://cosmopedia.xyz/api/v1/discussions?limit=5
curl https://cosmopedia.xyz/api/v1/trending

Endpoints (41)

/api/v1/discussionsList forum topics · limit, offset, category

/api/v1/discussions/:idGet topic with posts · topic id

/api/v1/docsList documentation pages · source, limit, offset

/api/v1/docs/:idGet full doc page content · doc id

/api/v1/whitepapersList all whitepapers

/api/v1/whitepapers/:slugGet whitepaper with extracted text · slug

/api/v1/trendingTrending content this week

/api/v1/videosYouTube videos · channel, limit, offset

/api/v1/reposIndexed GitHub repositories

/api/v1/codeGitHub issues and PRs browser · repo, state, type, q, limit, offset

/api/v1/videos/:idSingle YouTube video metadata + transcript · video id

/api/v1/github-discussionsGitHub Discussions · repo, category, limit, offset

/api/v1/github-discussions/:idSingle discussion with body + comments · discussion node id

/api/v1/searches/popularTop human search queries on /search · window (days, 1-90), limit

/api/v1/searches/zeroDistinct search queries that returned 0 results - content-gap signal · window, limit

/api/v1/sourcesDiscovery: one row per content type with current count + last-synced timestamp

/api/v1/registrySource registry: every Cosmos source with licence, tier, precedence, as_of, confidence and the last liveness probe · category, tier, ingested (true|false), id

/api/v1/csp-violationsAggregated CSP violations grouped by directive - for security monitoring dashboards · window (days, 1-90), limit (top blocked_uris per directive, 1-25)

/api/v1/openapi.jsonOpenAPI 3.1 description of every endpoint - feed to Swagger UI / OpenAI function-calling / Postman

/api/v1/referenceInteractive API reference (Scalar) rendered from the OpenAPI spec - open in a browser to explore + try endpoints

/api/v1/hub/chain-stateCurrent Cosmos Hub chain state from an LCD: block height, upgrade plan, app version, governance/staking/slashing/distribution/mint params

/api/v1/hub/proposalsList Hub governance proposals from chain state · status, kind, q, include_spam, limit, offset

/api/v1/hub/proposals/:idGet one Hub proposal: timeline, deposit, vote shares, executed messages, forum thread, text excerpt · proposal id

/api/v1/hub/upgradesHub software-upgrade timeline with GitHub release cross-check and the Polkachu third-party reading · limit

/api/v1/chain-upgradesUpcoming upgrades of Cosmos chains other than the Hub, from Polkachu · network, include_past, limit

/api/v1/chainsList Cosmos chains from the community chain-registry · q, status (live|killed|upcoming; defaults to live, which is 226 of 262), limit

/api/v1/chains/:nameGet one chain: prefix, daemon, versions, tokens, explorers, public endpoints · chain name or id

/api/v1/chains/:name/ibc-channelsIBC channels of a chain from the chain-registry · counterparty, status (active|inactive|untagged|any), preferred_only, limit

/api/v1/advisoriesSearch Cosmos stack security advisories (ASA, ISA, GHSA, CWA) · q, severity, repo, kind (asa|isa|cwa|ghsa), limit, offset

/api/v1/advisories/:idGet one advisory by id; an id shared by several advisories returns all of them · advisory id, e.g. ASA-2025-004

/api/v1/specsSearch ADRs, RFCs and ICS standards by status · q, kind (adr|rfc|ics), status, scope (sdk|cometbft|ibc|hub), series (defaults to excluding the legacy 'tendermint-core' series, whose numbers collide with the current ones; pass series=all for all 218), limit, offset

/api/v1/specs/:labelGet one ADR/RFC/ICS by label, with what it supersedes or was superseded by · label e.g. ADR-065; scope

/api/v1/incidentsList post-mortems and incident reports · area, year, limit

/api/v1/auditsList security audit reports · q, project, limit

/api/v1/validatorsValidators of a chain from cosmos.directory: rank, commission, missed blocks, jailed/active · chain, q, active_only, jailed_only, limit, offset

/api/v1/validators/:nameOne validator by operator address or exact moniker · operator address or moniker; chain

/api/v1/endpoint-status/:chainPublic RPC/REST health per chain as cosmos.directory last saw it · chain name

/api/v1/releasesTagged releases of the indexed repositories, newest first; drafts excluded · repo, page, limit

/api/v1/releases/:idOne release with its notes, cut to the repository licence · release id, e.g. cosmos/[email protected]

/api/v1/changesWhat changed recently across releases, proposals, advisories, incidents and forum · days (1-90, default 14), limit

Rate limits

/mcp60 req / 15 min per IP

/api/v1/search20 req / min per IP

/api/v1/*120 req / 15 min per IP

Limits returned in RateLimit-* headers. On 429, check Retry-After.