@moonbanking/mcp-server 1.2.0 → 1.5.1

package/.github/workflows/npm-publish.yml

@@ -169,39 +169,124 @@ jobs:
           token: ${{ secrets.SYNC_DOCS_TOKEN }}
           path: moonbanking
 
-      - name: Update documentation
+      - name: Update main MCP documentation
+        shell: bash
         run: |
           # Create the target directory if it doesn't exist
           mkdir -p moonbanking/apps/docs/app/mcp
-          
+
           # Create the new content with prepended metadata
           cat > moonbanking/apps/docs/app/mcp/page.mdx << 'EOF'
-          {/* 
-            DO NOT EDIT THIS FILE DIRECTLY! 
-          
+          {/*
+            DO NOT EDIT THIS FILE DIRECTLY!
+
             It is automatically generated by the npm-publish GitHub Action in
             the moonbanking/mcp-server repository.
           */}
-          
+
           export const metadata = {
             title: `MCP`,
             description: `Create AI agents using Moon Banking's MCP server. Get high-quality data about banks worldwide from your favorite LLM platform with Moon Banking's MCP.`,
           };
-          
-          <ApiKeyNote featureName="MCP" />
-          
+
           EOF
-          
+
           # Append the README content
           cat mcp-server/README.md >> moonbanking/apps/docs/app/mcp/page.mdx
-          
-          echo "✅ Documentation updated"
+
+          # Rewrite GitHub-relative markdown links so they resolve to docs-app routes:
+          #   ./README.md   → /mcp
+          #   ./<slug>.md   → /<slug>
+          # Also handles the bare-form variants (without `./`).
+          sed -i -E \
+            -e 's#\]\((\./)?README\.md\)#](/mcp)#g' \
+            -e 's#\]\((\./)?([A-Za-z][A-Za-z0-9-]*)\.md\)#](/\2)#g' \
+            moonbanking/apps/docs/app/mcp/page.mdx
+
+          echo "✅ Main MCP documentation updated"
+
+      - name: Update platform documentation
+        shell: bash
+        run: |
+          # Sync each per-platform doc page (e.g. mcp-server/cursor.md, which
+          # lives at the package root alongside README.md) into the docs app
+          # as a TOP-LEVEL route (apps/docs/app/cursor/page.mdx).
+          # Title + description are parsed from the markdown file itself, so
+          # adding a new platform in the moonbanking monorepo generator
+          # automatically flows through this workflow with no further edits.
+
+          shopt -s nullglob
+          synced=0
+
+          # Files we should NOT treat as platform docs even if they end in .md.
+          skip_regex='^(README|CHANGELOG|LICENSE|CONTRIBUTING|CODE_OF_CONDUCT|SECURITY)$'
+
+          for src in mcp-server/*.md; do
+            slug="$(basename "$src" .md)"
+
+            # Skip non-platform markdown at the package root.
+            if [[ "$slug" =~ $skip_regex ]]; then
+              echo "↪︎  Skipping $slug.md (non-platform file)"
+              continue
+            fi
+
+            # Extract `<Name>` from `# Moon Banking MCP for <Name>` (first H1).
+            title="$(sed -n 's/^# Moon Banking MCP for \(.*\)$/\1/p' "$src" | head -n1)"
+            # Extract description from the first `> ...` blockquote line.
+            description="$(sed -n 's/^> \(.*\)$/\1/p' "$src" | head -n1)"
+
+            # If the file doesn't look like a platform doc, bail rather than
+            # publish a malformed docs page.
+            if [ -z "$title" ]; then
+              echo "⚠️  ${slug}.md does not look like a platform doc (no '# Moon Banking MCP for ...' H1) — skipping."
+              continue
+            fi
+
+            if [ -z "$description" ]; then
+              description="Connect ${title} to the Moon Banking MCP server."
+            fi
+
+            dest_dir="moonbanking/apps/docs/app/$slug"
+            mkdir -p "$dest_dir"
+            dest="$dest_dir/page.mdx"
+
+            {
+              echo '{/*'
+              echo '  DO NOT EDIT THIS FILE DIRECTLY!'
+              echo ''
+              echo '  It is automatically generated by the npm-publish GitHub Action in'
+              echo '  the moonbanking/mcp-server repository.'
+              echo '*/}'
+              echo ''
+              echo 'export const metadata = {'
+              echo "  title: \`MCP — ${title}\`,"
+              echo "  description: \`${description}\`,"
+              echo '};'
+              echo ''
+            } > "$dest"
+
+            cat "$src" >> "$dest"
+
+            # Rewrite GitHub-relative markdown links so they resolve to
+            # docs-app routes:
+            #   ./README.md  → /mcp
+            #   ./<slug>.md  → /<slug>
+            sed -i -E \
+              -e 's#\]\((\./)?README\.md\)#](/mcp)#g' \
+              -e 's#\]\((\./)?([A-Za-z][A-Za-z0-9-]*)\.md\)#](/\2)#g' \
+              "$dest"
+
+            echo "✅ Synced ${slug}.md → apps/docs/app/${slug}/page.mdx"
+            synced=$((synced + 1))
+          done
+
+          echo "📚 ${synced} platform docs synced"
 
       - name: Check for changes
         id: check_changes
         run: |
           cd moonbanking
-          if git diff --quiet apps/docs/app/mcp/page.mdx; then
+          if [ -z "$(git status --porcelain apps/docs/app/)" ]; then
             echo "has_changes=false" >> $GITHUB_OUTPUT
             echo "ℹ️ No changes detected in documentation"
           else
@@ -221,16 +306,29 @@ jobs:
           title: 'docs: sync MCP documentation v${{ needs.publish.outputs.version }}'
           body: |
             ## 🔄 Automated Documentation Sync
-            
+
             This PR automatically syncs the MCP server documentation from the [mcp-server repository](https://github.com/moonbanking/mcp-server).
-            
+
             **Version:** v${{ needs.publish.outputs.version }}
-            **Source:** README.md from mcp-server
-            **Target:** apps/docs/app/mcp/page.mdx
-            
+
+            ### Sources → targets
+
+            | Source (mcp-server root) | Target (moonbanking docs) |
+            | --- | --- |
+            | `README.md` | `apps/docs/app/mcp/page.mdx` |
+            | `<slug>.md` (cursor, claude, …) | `apps/docs/app/<slug>/page.mdx` (top-level route, one per MCP client) |
+
+            ### Link rewriting
+
+            GitHub-relative markdown links inside the source files are rewritten at sync time so they resolve to docs-app routes:
+
+            - `./README.md` → `/mcp`
+            - `./<slug>.md` → `/<slug>`
+
             ### Changes
-            - Updated MCP documentation with latest content from mcp-server v${{ needs.publish.outputs.version }}
-            
+            - Updated main MCP documentation with latest content from mcp-server v${{ needs.publish.outputs.version }}
+            - Synced per-platform setup guides (Claude, Cursor, Grok, ChatGPT, VS Code, Windsurf, Zed, Claude Code, MCP Inspector, …) to their own top-level docs pages
+
             ---
             *This PR was automatically created by the npm-publish GitHub Action*
           labels: |
@@ -245,12 +343,13 @@ jobs:
             echo "Created pull request to sync MCP documentation to getfullup/moonbanking repository." >> $GITHUB_STEP_SUMMARY
             echo "" >> $GITHUB_STEP_SUMMARY
             echo "**Version:** v${{ needs.publish.outputs.version }}" >> $GITHUB_STEP_SUMMARY
-            echo "**Target File:** apps/docs/app/mcp/page.mdx" >> $GITHUB_STEP_SUMMARY
+            echo "**Targets:**" >> $GITHUB_STEP_SUMMARY
+            echo "- apps/docs/app/mcp/page.mdx (main MCP page from README.md)" >> $GITHUB_STEP_SUMMARY
+            echo "- apps/docs/app/<slug>/page.mdx (one per platform, from <slug>.md at package root)" >> $GITHUB_STEP_SUMMARY
           else
             echo "## ℹ️ No Documentation Changes" >> $GITHUB_STEP_SUMMARY
             echo "" >> $GITHUB_STEP_SUMMARY
             echo "Documentation is already up to date. No pull request created." >> $GITHUB_STEP_SUMMARY
             echo "" >> $GITHUB_STEP_SUMMARY
             echo "**Version:** v${{ needs.publish.outputs.version }}" >> $GITHUB_STEP_SUMMARY
-            echo "**Target File:** apps/docs/app/mcp/page.mdx" >> $GITHUB_STEP_SUMMARY
-          fi
+          fi

package/README.md

@@ -1,8 +1,72 @@
 # Moon Banking MCP Server
 
-The Moon Banking MCP server is generated from the [OpenAPI specification](https://github.com/moonbanking/moonbanking-openapi).
+Moon Banking is a global directory of consumer and business banks with structured, community-rated scores across 14 categories — customer service, fees & pricing, digital experience, crypto friendliness, security & trust, lending, business banking, international banking, transparency, and more. The Moon Banking MCP server exposes that entire dataset — every bank, country, score, vote, and user story — as live tools your AI agent can call, so answers about real-world banking are grounded in fresh Moon Banking data instead of stale training-set guesses.
 
-## Installation
+Once connected, you can ask questions like *"which crypto-friendly banks operate in Brazil?"*, *"compare digital-experience scores for the top US challenger banks"*, or *"summarize recent user stories about fees at HSBC UK"* and get tool-grounded, citable answers backed by the same data that powers [moonbanking.com](https://moonbanking.com).
+
+The server is generated from the public [OpenAPI specification](https://github.com/moonbanking/moonbanking-openapi) and ships as both a hosted OAuth endpoint at `https://mcp.moonbanking.com/mcp` and a stdio npm package (`@moonbanking/mcp-server`) — so you can connect it to Claude, Cursor, Grok, ChatGPT, VS Code, Windsurf, Zed, and any other [Model Context Protocol](https://modelcontextprotocol.io) client.
+
+## Client-specific setup guides
+
+If you just want to wire Moon Banking up to a specific client, jump straight to its guide. Each one covers both the hosted OAuth setup and the self-hosted stdio fallback.
+
+| Client | Guide |
+| --- | --- |
+| Claude (Desktop & web) | [claude](./claude.md) |
+| Claude Code | [claude-code](./claude-code.md) |
+| Cursor | [cursor](./cursor.md) |
+| Windsurf | [windsurf](./windsurf.md) |
+| VS Code (GitHub Copilot) | [vscode](./vscode.md) |
+| Zed | [zed](./zed.md) |
+| ChatGPT | [chatgpt](./chatgpt.md) |
+| Grok (xAI) | [grok](./grok.md) |
+| MCP Inspector (testing) | [mcp-inspector](./mcp-inspector.md) |
+
+The rest of this README covers the underlying authentication options and configuration shapes.
+
+## Authentication
+
+You can connect to Moon Banking over MCP using **either** of two auth methods:
+
+| Method | Best for | API key required? |
+| --- | --- | --- |
+| **Hosted OAuth server** (recommended) | Claude, Cursor, Grok, ChatGPT, and any MCP client that supports remote/streamable HTTP MCP. Users sign in to Moon Banking in a browser — no key handling. | No |
+| **Self-hosted stdio package** (this npm package) | Local scripts, agents, or clients that only support stdio MCP. | Yes |
+
+Both methods expose the same tool surface; pick whichever matches your client.
+
+## Hosted MCP server (OAuth)
+
+URL: `https://mcp.moonbanking.com/mcp` (Streamable HTTP, OAuth 2.0 with Dynamic Client Registration).
+
+Most modern MCP clients can connect by simply pointing at the URL — they will pop a browser window for the user to sign in to Moon Banking and obtain an access token automatically. No API key is exchanged or stored on the client side.
+
+```json
+{
+  "mcpServers": {
+    "moonbanking": {
+      "url": "https://mcp.moonbanking.com/mcp"
+    }
+  }
+}
+```
+
+For clients that don't yet speak remote MCP natively (eg. older ChatGPT configurations), the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge can wrap the hosted endpoint as a stdio command:
+
+```json
+{
+  "mcpServers": {
+    "moonbanking": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://mcp.moonbanking.com/mcp"]
+    }
+  }
+}
+```
+
+## Self-hosted (API key)
+
+If you prefer to run the MCP server locally as a stdio process — for example to embed it in an automation that doesn't have a browser available for OAuth — install this npm package and authenticate with a Moon Banking API key.
 
 ### Direct invocation
 
@@ -34,22 +98,6 @@ For clients with a configuration JSON, it might look something like this:
 }
 ```
 
-### Cursor
-
-If you use Cursor, you can install the MCP server by using the button below. You will need to set your environment variables
-in Cursor's `mcp.json`, which can be found in Cursor Settings > Tools & MCP > New MCP Server.
-
-[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=moonbanking-mcp&config=eyJlbnYiOnsiTU9PTl9CQU5LSU5HX0FQSV9LRVkiOiJTZXQgeW91ciBNT09OX0JBTktJTkdfQVBJX0tFWSBoZXJlLiJ9LCJjb21tYW5kIjoibnB4IC15IEBtb29uYmFua2luZy9tY3Atc2VydmVyIn0%3D)
-
-### Claude Code
-
-If you use Claude Code, you can install the MCP server by running the command below in your terminal. You will need to set your
-environment variables in Claude Code's `.claude.json`, which can be found in your home directory.
-
-```
-claude mcp add --transport stdio moonbanking_api --env MOON_BANKING_API_KEY="Your MOON_BANKING_API_KEY here." -- npx -y @moonbanking/mcp-server
-```
-
 ## Filter Specific Tools
 
 You can limit which tools are exposed by using the `--tool` flag:

package/chatgpt.md

@@ -0,0 +1,83 @@
+# Moon Banking MCP for ChatGPT
+
+> Add the Moon Banking MCP server to ChatGPT via Custom Connectors or a Custom GPT.
+
+ChatGPT is great at fluent answers and weaker on fresh, structured facts about specific institutions. Adding the Moon Banking MCP as a Custom Connector gives ChatGPT live, tool-grounded access to every bank, country, community-rated score across 14 categories (customer service, fees & pricing, digital experience, crypto friendliness, security & trust, lending, transparency, and more), vote, and user story Moon Banking tracks.
+
+Use it for everything from *"which crypto-friendly banks operate in Argentina?"* to *"compare the top three US challenger banks on fees and digital experience"* to *"summarize what users are saying about Wells Fargo's customer service this year"* — and get citable, data-grounded answers instead of generic summaries.
+
+ChatGPT supports MCP through two distinct surfaces, and the right choice depends on your plan.
+
+## Recommended: hosted (OAuth) via Custom Connectors
+
+ChatGPT Plus, Pro, Team, Enterprise, and Edu users can add the Moon Banking server as a **Custom Connector** (the same mechanism that powers the official Notion, Gmail, etc. connectors).
+
+1. Open ChatGPT → **Settings → Connectors → Custom Connectors → Add custom connector**.
+2. Enter:
+   - **Name:** `Moon Banking`
+   - **URL:** `https://mcp.moonbanking.com/mcp`
+3. Save. ChatGPT will open a browser tab to authenticate with Moon Banking. Approve.
+4. In any chat, click the **+** button and enable the Moon Banking connector.
+
+> Custom Connectors require a paid plan with Connectors enabled for your region. Availability may vary; check [help.openai.com](https://help.openai.com) for current rollout status.
+
+## Alternative: stdio bridge for Custom GPTs / older setups
+
+If your plan doesn't expose Custom Connectors, you can wrap the hosted endpoint with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) for any tooling that accepts stdio MCP (eg. a self-hosted ChatGPT-compatible agent):
+
+```json
+{
+  "mcpServers": {
+    "moonbanking": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://mcp.moonbanking.com/mcp"]
+    }
+  }
+}
+```
+
+You can also run the stdio-only API-key package directly:
+
+```json
+{
+  "mcpServers": {
+    "moonbanking-mcp": {
+      "command": "npx",
+      "args": ["-y", "@moonbanking/mcp-server"],
+      "env": {
+        "MOON_BANKING_API_KEY": "Bearer mb_sk_..."
+      }
+    }
+  }
+}
+```
+
+## Verify the connection
+
+Start a new chat and prompt:
+
+> Use the Moon Banking connector to find banks in Singapore with strong fees and pricing scores.
+
+## Troubleshooting
+
+- **Connector option is missing.** Custom Connectors are gated by plan and region. Try the `mcp-remote` stdio bridge instead.
+- **OAuth returns to a 404.** Make sure your ChatGPT browser session is logged in and that pop-ups are allowed for chatgpt.com.
+
+
+## Available tools
+
+The Moon Banking MCP server exposes the following tools (identical across every client):
+
+- `bank_getByHostname`
+- `bank_get`
+- `bank_getById`
+- `bank_semanticSearch`
+- `bankVote_get`
+- `country_get`
+- `country_getByCountryCode`
+- `story_get`
+- `story_getById`
+- `world_getOverview`
+- `search_get`
+
+Full descriptions live on the [main MCP page](./README.md).

package/claude-code.md

@@ -0,0 +1,74 @@
+# Moon Banking MCP for Claude Code
+
+> Add the Moon Banking MCP server to the Claude Code CLI for use in terminal-driven coding sessions.
+
+Claude Code is the right tool when you're scripting against APIs, automating data work, or hacking on a fintech backend without leaving your terminal. Adding the Moon Banking MCP gives the CLI agent live access to the entire Moon Banking dataset — banks, countries, community-rated scores across 14 categories (customer service, fees & pricing, digital experience, crypto friendliness, lending, transparency, …), user votes, user stories, and global rankings — over either the hosted OAuth endpoint or a local stdio process.
+
+Typical uses: seeding a fintech database with realistic bank records, generating evaluation datasets that need real institutions, prototyping "find me a bank that…" features, or pausing mid-script to ask *"which US banks have the highest customer-service scores?"* without context-switching to a browser.
+
+Claude Code is Anthropic's terminal CLI. It supports both **remote** (HTTP/Streamable HTTP) and **stdio** MCP transports.
+
+## Recommended: hosted (OAuth)
+
+Run this once in any directory:
+
+```bash
+claude mcp add --transport http moonbanking https://mcp.moonbanking.com/mcp
+```
+
+The first time you invoke a Moon Banking tool, Claude Code will print a one-time URL and ask you to authenticate in your browser. The resulting OAuth token is cached on disk and reused across sessions.
+
+To install only for the current project (instead of globally), pass `--scope project`:
+
+```bash
+claude mcp add --transport http --scope project moonbanking https://mcp.moonbanking.com/mcp
+```
+
+The project-scoped config lives in `.claude.json` at the project root and can be committed to source control if you want every developer on the team to share it.
+
+## Alternative: self-hosted (API key)
+
+```bash
+claude mcp add --transport stdio moonbanking \
+  --env MOON_BANKING_API_KEY="Bearer mb_sk_..." \
+  -- npx -y @moonbanking/mcp-server
+```
+
+This launches a local stdio MCP server that authenticates with your API key on every call.
+
+## Verify the connection
+
+```bash
+claude mcp list
+```
+
+You should see `moonbanking` listed with a connection status of `connected`. Then start a session and try:
+
+```
+> Find the highest-rated bank in Switzerland for crypto users.
+```
+
+## Troubleshooting
+
+- **`Failed to authenticate`** Run `claude mcp remove moonbanking` and re-add to clear the cached token.
+- **No tools available.** Run `claude mcp list` — if the server appears with a red status, run `claude mcp logs moonbanking` to inspect the error.
+- **Pro plan required.** The MCP API rejects non-Pro Moon Banking accounts; [upgrade to Pro](https://moonbanking.com/pro).
+
+
+## Available tools
+
+The Moon Banking MCP server exposes the following tools (identical across every client):
+
+- `bank_getByHostname`
+- `bank_get`
+- `bank_getById`
+- `bank_semanticSearch`
+- `bankVote_get`
+- `country_get`
+- `country_getByCountryCode`
+- `story_get`
+- `story_getById`
+- `world_getOverview`
+- `search_get`
+
+Full descriptions live on the [main MCP page](./README.md).

package/claude.md

@@ -0,0 +1,95 @@
+# Moon Banking MCP for Claude
+
+> Add the Moon Banking MCP server to Claude Desktop and claude.ai as a custom connector.
+
+Claude is one of the strongest models for nuanced research and writing, and one of its biggest weak points is fresh, structured data about specific institutions. The Moon Banking MCP gives Claude live access to every bank, country, community-rated score across 14 categories (customer service, fees & pricing, digital experience, crypto friendliness, security & trust, lending, transparency, and more), vote, and user story in the Moon Banking database — so questions about real-world banks come back with citable, tool-grounded facts instead of generic training-data summaries.
+
+Try *"draft a comparison of the three highest-rated digital banks in Germany, then tell me which has the best reviews on fees"*, *"summarize what users are saying about HSBC's customer service this year"*, or *"which banks in Brazil rank highest on crypto friendliness?"* — Claude will pull the data on demand and reason over it in-line.
+
+Claude Desktop and claude.ai both support remote MCP servers as **custom connectors**. The hosted Moon Banking endpoint uses Streamable HTTP with OAuth, which both clients handle out of the box.
+
+## Recommended: hosted (OAuth)
+
+### Claude Desktop
+
+1. Open **Settings → Connectors** (or **Settings → Developer → Add custom connector**, depending on your version).
+2. Choose **Add custom connector**.
+3. Set:
+   - **Name:** `Moon Banking`
+   - **URL:** `https://mcp.moonbanking.com/mcp`
+4. Click **Add**. Claude will open a browser window asking you to sign in to Moon Banking. Approve the connection.
+5. Back in Claude, toggle the **Moon Banking** connector on in any chat.
+
+If you prefer to edit the config file directly, on macOS it lives at `~/Library/Application Support/Claude/claude_desktop_config.json`. On Windows it's `%APPDATA%\Claude\claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "moonbanking": {
+      "url": "https://mcp.moonbanking.com/mcp"
+    }
+  }
+}
+```
+
+Restart Claude Desktop after editing.
+
+### claude.ai (web)
+
+1. Sign in at [claude.ai](https://claude.ai) on a Pro, Team, or Enterprise plan (custom connectors require a paid plan).
+2. Go to **Settings → Connectors → Add custom connector**.
+3. Paste `https://mcp.moonbanking.com/mcp` and confirm.
+4. Approve the OAuth prompt that opens.
+
+## Alternative: self-hosted (API key)
+
+If you need a stdio connection (eg. air-gapped use or a service account), Claude Desktop can spawn the published npm package locally. Add this to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "moonbanking-mcp": {
+      "command": "npx",
+      "args": ["-y", "@moonbanking/mcp-server"],
+      "env": {
+        "MOON_BANKING_API_KEY": "Bearer mb_sk_..."
+      }
+    }
+  }
+}
+```
+
+Generate the API key at [moonbanking.com/settings/api/manage-api-keys](https://moonbanking.com/settings/api/manage-api-keys) and restart Claude.
+
+## Verify the connection
+
+Start a new conversation in Claude and ask:
+
+> Using the Moon Banking connector, find banks in Brazil that are known for being crypto-friendly.
+
+Claude should call tools like `bank_semanticSearch` or `country_getByCountryCode` and reply with real Moon Banking data.
+
+## Troubleshooting
+
+- **Connector shows as disconnected.** Click the connector in Settings and re-run the auth flow. If your access token expired Claude will need to re-authenticate.
+- **`Tool list is empty`** Make sure your account has been granted Pro access at moonbanking.com. The MCP endpoint requires a Pro subscription.
+- **Cannot add connector.** Claude.ai's custom connectors are gated to paid plans. Claude Desktop has fewer restrictions.
+
+
+## Available tools
+
+The Moon Banking MCP server exposes the following tools (identical across every client):
+
+- `bank_getByHostname`
+- `bank_get`
+- `bank_getById`
+- `bank_semanticSearch`
+- `bankVote_get`
+- `country_get`
+- `country_getByCountryCode`
+- `story_get`
+- `story_getById`
+- `world_getOverview`
+- `search_get`
+
+Full descriptions live on the [main MCP page](./README.md).

package/cursor.md

@@ -0,0 +1,86 @@
+# Moon Banking MCP for Cursor
+
+> Connect Cursor to the Moon Banking MCP server so the AI can query banks, countries, votes, and stories with one-click OAuth.
+
+Cursor's agent is excellent at writing code but has no built-in knowledge of specific banks, their hostnames, fee structures, or how real customers rate them. Wiring in the Moon Banking MCP closes that gap: Cursor gains live access to every bank Moon Banking tracks — name, country, primary hostname, rank, community-rated scores across 14 categories (customer service, fees & pricing, digital experience, crypto friendliness, security & trust, lending, and more) — plus the user-submitted stories backing those scores.
+
+Useful when you're scaffolding a fintech project, validating bank hostnames you see in code, generating realistic test fixtures, or just prompting *"find me a crypto-friendly business bank in Singapore and stub out a client for its public API"* mid-session. Answers are grounded in fresh Moon Banking data — not whatever your model memorized last year.
+
+Cursor speaks remote MCP natively over Streamable HTTP. The fastest setup is to point Cursor at the hosted endpoint — Cursor handles the OAuth flow in a browser tab automatically.
+
+## Recommended: hosted (OAuth)
+
+### Option A — Click to install
+
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=moonbanking&config=eyJ1cmwiOiJodHRwczovL21jcC5tb29uYmFua2luZy5jb20vbWNwIn0%3D)
+
+### Option B — Edit `mcp.json` directly
+
+Open Cursor and go to **Settings → Tools & MCP → New MCP Server**, or edit your global config at `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "moonbanking": {
+      "url": "https://mcp.moonbanking.com/mcp"
+    }
+  }
+}
+```
+
+For project-scoped install instead, drop the same JSON at `.cursor/mcp.json` inside your repository.
+
+The first time Cursor connects, it will open a browser window asking you to sign in to Moon Banking. After that, the connection persists across restarts.
+
+## Alternative: self-hosted (API key)
+
+If you would rather run the MCP server locally as a stdio process (eg. you are on a machine without a browser, or you want to use a service API key), Cursor can spawn the published npm package.
+
+```json
+{
+  "mcpServers": {
+    "moonbanking-mcp": {
+      "command": "npx",
+      "args": ["-y", "@moonbanking/mcp-server"],
+      "env": {
+        "MOON_BANKING_API_KEY": "Bearer mb_sk_..."
+      }
+    }
+  }
+}
+```
+
+Generate an API key at [moonbanking.com/settings/api/manage-api-keys](https://moonbanking.com/settings/api/manage-api-keys).
+
+## Verify the connection
+
+Open the Cursor chat panel and look for the **MCP** indicator beside the model picker — it should show `moonbanking` with a green dot and the tool count. You can also ask the agent something like:
+
+> What are the top three banks in Germany right now?
+
+If it responds using the `bank_get` and `country_get` tools, the connection is working.
+
+## Troubleshooting
+
+- **Tools list is empty.** Cursor may have cached an unauthenticated session. Remove the entry from `mcp.json`, restart Cursor, and re-add it. If the issue persists, run `npx @modelcontextprotocol/inspector` against `https://mcp.moonbanking.com/mcp` to confirm the server is reachable from your network.
+- **OAuth window closes immediately.** Make sure your default browser is signed in to Moon Banking, or sign in first at [moonbanking.com](https://moonbanking.com) and retry.
+- **403 errors after sign-in.** Your Moon Banking account must be on a Pro plan to use the MCP API. [Upgrade to Pro](https://moonbanking.com/pro).
+
+
+## Available tools
+
+The Moon Banking MCP server exposes the following tools (identical across every client):
+
+- `bank_getByHostname`
+- `bank_get`
+- `bank_getById`
+- `bank_semanticSearch`
+- `bankVote_get`
+- `country_get`
+- `country_getByCountryCode`
+- `story_get`
+- `story_getById`
+- `world_getOverview`
+- `search_get`
+
+Full descriptions live on the [main MCP page](./README.md).

package/grok.md

@@ -0,0 +1,71 @@
+# Moon Banking MCP for Grok
+
+> Add the Moon Banking MCP server to Grok (xAI) as a custom connector.
+
+Grok is built around live, current information — and the Moon Banking MCP fits that wheelhouse cleanly. Once added as a connector, Grok can query the Moon Banking dataset on demand — every bank, country, community-rated score across 14 categories (customer service, fees & pricing, digital experience, crypto friendliness, security & trust, lending, transparency, …), vote, and user story — and combine it with the real-time signal Grok already pulls from X and the open web.
+
+Try *"which European banks rank highest on crypto friendliness right now, and what are people saying about them on X?"*, *"compare digital-experience scores across the top five US online banks"*, or *"what are users saying about Revolut's fees lately?"* — Grok will weave Moon Banking's structured data together with whatever it finds in the wild.
+
+Grok supports remote MCP servers via **Connectors**, available in the xAI Console and inside grok.com for Grok 4 and newer.
+
+## Recommended: hosted (OAuth)
+
+1. Go to [grok.com](https://grok.com) (or the xAI Console) and open **Settings → Connectors**.
+2. Choose **Add custom connector** (or **Add MCP server**, depending on your build).
+3. Enter:
+   - **Name:** `Moon Banking`
+   - **URL:** `https://mcp.moonbanking.com/mcp`
+4. Approve the OAuth prompt that opens in your browser.
+5. In any chat, enable the Moon Banking connector from the input toolbar.
+
+## Alternative: stdio bridge
+
+For environments without a Connectors UI (eg. local Grok-compatible agents, self-hosted setups, or API-key-based access), use the stdio package or wrap the hosted URL with `mcp-remote`:
+
+```json
+{
+  "mcpServers": {
+    "moonbanking": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://mcp.moonbanking.com/mcp"]
+    },
+    "moonbanking-apikey": {
+      "command": "npx",
+      "args": ["-y", "@moonbanking/mcp-server"],
+      "env": {
+        "MOON_BANKING_API_KEY": "Bearer mb_sk_..."
+      }
+    }
+  }
+}
+```
+
+## Verify the connection
+
+In Grok, prompt:
+
+> Using the Moon Banking connector, list five banks in the US that rank highly on customer service.
+
+## Troubleshooting
+
+- **Connectors panel is missing.** Custom MCP connectors are a Grok 4 / SuperGrok feature. Older Grok versions don't support them.
+- **OAuth fails silently.** Try the flow in a private/incognito window; some browser extensions interfere with OAuth callbacks.
+
+
+## Available tools
+
+The Moon Banking MCP server exposes the following tools (identical across every client):
+
+- `bank_getByHostname`
+- `bank_get`
+- `bank_getById`
+- `bank_semanticSearch`
+- `bankVote_get`
+- `country_get`
+- `country_getByCountryCode`
+- `story_get`
+- `story_getById`
+- `world_getOverview`
+- `search_get`
+
+Full descriptions live on the [main MCP page](./README.md).

package/mcp-inspector.md

@@ -0,0 +1,60 @@
+# Moon Banking MCP for MCP Inspector
+
+> Test the Moon Banking MCP server with Anthropic's MCP Inspector before wiring it into a client.
+
+MCP Inspector is the sanity check before plugging Moon Banking into Claude, Cursor, Grok, ChatGPT, or anywhere else. Point it at the hosted endpoint and you can see the full Moon Banking tool surface (11 tools across banks, countries, votes, stories, semantic search, and global overview), invoke each one with real arguments, and verify the OAuth flow works end-to-end — all before you commit a single line to a real client's config.
+
+It's also the easiest way to confirm a new MCP client implementation you're building yourself supports Streamable HTTP plus OAuth with Dynamic Client Registration correctly: if Moon Banking works in the Inspector but not in your client, the difference is on your end, not the server's.
+
+[MCP Inspector](https://github.com/modelcontextprotocol/inspector) is the official debugger for MCP servers. Use it when you're integrating Moon Banking into a new client and want to verify that the OAuth flow and tool surface behave as expected.
+
+## Run the inspector
+
+```bash
+npx @modelcontextprotocol/inspector
+```
+
+A browser window opens at [http://localhost:6274](http://localhost:6274).
+
+## Connect to the hosted server
+
+1. **Transport:** `Streamable HTTP`
+2. **Server URL:** `https://mcp.moonbanking.com/mcp`
+3. Click **Connect**. The inspector will detect that the server requires OAuth, open a browser tab to authenticate with Moon Banking, and bring you back once you approve.
+4. In the **Tools** tab, you should see every Moon Banking tool. Click any of them, fill in arguments, and invoke them live.
+
+## Connect to the self-hosted stdio server
+
+If you're testing the API-key package, run the inspector against the local stdio process:
+
+```bash
+MOON_BANKING_API_KEY="Bearer mb_sk_..." \
+  npx @modelcontextprotocol/inspector npx -y @moonbanking/mcp-server
+```
+
+## What to look for
+
+- **Tools tab populated** — confirms the server is serving the tool list.
+- **Successful tool call** — confirms upstream API auth is working.
+- **Resources / Prompts tabs empty** — expected; Moon Banking exposes tools only.
+
+If the inspector shows `401 Unauthorized` or `403 Forbidden`, refer to the troubleshooting sections of the client-specific pages; the root cause is usually a Moon Banking account that isn't on the Pro plan, or a stale OAuth token in the inspector's cache (clear it with the **Disconnect** button).
+
+
+## Available tools
+
+The Moon Banking MCP server exposes the following tools (identical across every client):
+
+- `bank_getByHostname`
+- `bank_get`
+- `bank_getById`
+- `bank_semanticSearch`
+- `bankVote_get`
+- `country_get`
+- `country_getByCountryCode`
+- `story_get`
+- `story_getById`
+- `world_getOverview`
+- `search_get`
+
+Full descriptions live on the [main MCP page](./README.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moonbanking/mcp-server",
-  "version": "1.2.0",
+  "version": "1.5.1",
   "description": "# Welcome to the Moon Banking API!\n\nEnjoy the documentation and happy coding. Share this spec with your LLM of choice to speed up your development, or take a look at our MCP server and various SDKs.\n\n### More information\n\nFor more information about the Moon Banking API, please visit the [Moon Banking Documentation](https://docs.moonbanking.com).",
   "main": "dist/index.js",
   "bin": {

package/vscode.md

@@ -0,0 +1,75 @@
+# Moon Banking MCP for VS Code
+
+> Connect VS Code (with GitHub Copilot Chat MCP support) to the Moon Banking MCP server.
+
+GitHub Copilot's MCP support turns VS Code into a coding agent that can talk to live external data — not just whatever was in its training set. With the Moon Banking MCP plugged in, Copilot can answer questions about specific banks while you code: names, hostnames, country rank, community-rated scores across 14 categories (customer service, fees & pricing, digital experience, crypto friendliness, lending, …), and the user stories behind those scores.
+
+Useful when you're integrating with a bank's API, validating hostnames in code, shipping a feature that displays real bank ratings, or just asking *"which banks in Mexico score highest on digital experience?"* in the middle of a session — Copilot will route the question through the MCP server and reply with citable data.
+
+Recent versions of VS Code expose MCP servers to GitHub Copilot Chat via an `mcp.json` configuration. Both remote HTTP and stdio transports are supported.
+
+## Recommended: hosted (OAuth)
+
+Create `.vscode/mcp.json` in your workspace (or the user-level equivalent) and add:
+
+```json
+{
+  "servers": {
+    "moonbanking": {
+      "type": "http",
+      "url": "https://mcp.moonbanking.com/mcp"
+    }
+  }
+}
+```
+
+Reload the window. The first time Copilot Chat invokes a Moon Banking tool, VS Code will pop a notification asking you to authenticate in your browser. After approval, the connection is reused for the rest of the session.
+
+## Alternative: self-hosted (API key)
+
+```json
+{
+  "servers": {
+    "moonbanking-mcp": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@moonbanking/mcp-server"],
+      "env": {
+        "MOON_BANKING_API_KEY": "Bearer mb_sk_..."
+      }
+    }
+  }
+}
+```
+
+## Verify the connection
+
+Open Copilot Chat and ask:
+
+> @workspace Using the Moon Banking MCP, find me three banks in France that score highly on digital experience.
+
+If the tools are connected, Copilot will reply with tool-call traces visible in the chat view.
+
+## Troubleshooting
+
+- **VS Code doesn't see the config.** Confirm you are on a recent version of VS Code (MCP support shipped in late 2025 / 2026). Older versions don't honor `mcp.json`.
+- **Auth never completes.** Make sure VS Code is allowed to open external URLs (`window.openUrl` setting). Corporate proxies may block the OAuth callback.
+
+
+## Available tools
+
+The Moon Banking MCP server exposes the following tools (identical across every client):
+
+- `bank_getByHostname`
+- `bank_get`
+- `bank_getById`
+- `bank_semanticSearch`
+- `bankVote_get`
+- `country_get`
+- `country_getByCountryCode`
+- `story_get`
+- `story_getById`
+- `world_getOverview`
+- `search_get`
+
+Full descriptions live on the [main MCP page](./README.md).

package/windsurf.md

@@ -0,0 +1,71 @@
+# Moon Banking MCP for Windsurf
+
+> Connect Windsurf (Codeium Cascade) to the Moon Banking MCP server.
+
+Windsurf's Cascade agent is built for long-running, multi-file coding tasks — exactly where having reliable external data matters. Wire in the Moon Banking MCP and Cascade gains live access to the entire Moon Banking dataset (banks, countries, community-rated scores across 14 categories, votes, user stories), so when your agent needs to know about a real bank — its hostname, country rank, crypto-friendliness score, or what users say about its fees — it asks instead of guessing.
+
+Useful for building banking-aware features, generating realistic test fixtures across an entire repo, or simply prompting *"find a crypto-friendly digital bank in Portugal and scaffold a project that integrates with its public services"* while Cascade does the heavy lifting.
+
+Windsurf's Cascade agent supports MCP via its `mcp_config.json` file. Both remote (HTTP) and stdio transports work.
+
+## Recommended: hosted (OAuth)
+
+Edit (or create) the global Windsurf config at `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "moonbanking": {
+      "serverUrl": "https://mcp.moonbanking.com/mcp"
+    }
+  }
+}
+```
+
+Restart Windsurf. The first request to a Moon Banking tool will trigger an OAuth flow in your browser. After approval, the tools become available to Cascade.
+
+## Alternative: self-hosted (API key)
+
+```json
+{
+  "mcpServers": {
+    "moonbanking-mcp": {
+      "command": "npx",
+      "args": ["-y", "@moonbanking/mcp-server"],
+      "env": {
+        "MOON_BANKING_API_KEY": "Bearer mb_sk_..."
+      }
+    }
+  }
+}
+```
+
+## Verify the connection
+
+Open Cascade and click the MCP toolbar icon — `moonbanking` should appear in the list along with its tools. Then ask:
+
+> List the top five banks in Japan by user rating.
+
+## Troubleshooting
+
+- **Server not detected.** Confirm Windsurf is reading the right config file: open **Cascade Settings → MCP** and verify the path it shows.
+- **Auth window won't open.** Some Linux distributions require a default browser to be configured (`xdg-settings set default-web-browser ...`).
+
+
+## Available tools
+
+The Moon Banking MCP server exposes the following tools (identical across every client):
+
+- `bank_getByHostname`
+- `bank_get`
+- `bank_getById`
+- `bank_semanticSearch`
+- `bankVote_get`
+- `country_get`
+- `country_getByCountryCode`
+- `story_get`
+- `story_getById`
+- `world_getOverview`
+- `search_get`
+
+Full descriptions live on the [main MCP page](./README.md).

package/zed.md

@@ -0,0 +1,72 @@
+# Moon Banking MCP for Zed
+
+> Connect the Zed editor to the Moon Banking MCP server via Context Servers.
+
+Zed's AI assistant is fast and stays out of your way — exactly what you want when you're moving through code. Connecting the Moon Banking MCP gives that assistant live access to the Moon Banking dataset: every bank, country, community-rated score across 14 categories (customer service, fees & pricing, digital experience, crypto friendliness, lending, …), vote, and user story. Questions about real banks come back with real data, with no perceptible latency hit on the rest of your workflow.
+
+Useful for scaffolding fintech projects, generating realistic test data, or just pulling up *"the five highest-rated business banks in Canada"* or *"which European banks have the best digital experience scores?"* without leaving the editor.
+
+Zed exposes MCP servers to its built-in AI assistant as **Context Servers**. Configure them in `~/.config/zed/settings.json` (or **Zed → Settings → Open settings**).
+
+## Recommended: hosted (OAuth)
+
+```json
+{
+  "context_servers": {
+    "moonbanking": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://mcp.moonbanking.com/mcp"]
+    }
+  }
+}
+```
+
+Zed's Context Servers currently expect a stdio command, so we wrap the hosted endpoint with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) — a tiny bridge that proxies stdio to remote Streamable HTTP and handles the OAuth flow in a browser tab.
+
+After saving, restart Zed. The first request to a Moon Banking tool opens a browser window for sign-in.
+
+## Alternative: self-hosted (API key)
+
+```json
+{
+  "context_servers": {
+    "moonbanking-mcp": {
+      "command": "npx",
+      "args": ["-y", "@moonbanking/mcp-server"],
+      "env": {
+        "MOON_BANKING_API_KEY": "Bearer mb_sk_..."
+      }
+    }
+  }
+}
+```
+
+## Verify the connection
+
+Open the Zed AI panel. The **Context Servers** section in the side panel should list `moonbanking` along with its tool count. Then ask:
+
+> Using Moon Banking, what are the most highly-rated banks in Brazil?
+
+## Troubleshooting
+
+- **`mcp-remote` is slow on first run.** It downloads on first invocation. Subsequent runs are cached.
+- **Auth never completes.** Confirm that `localhost` is reachable from your browser — `mcp-remote` uses a local callback port (`http://127.0.0.1:6274` by default).
+
+
+## Available tools
+
+The Moon Banking MCP server exposes the following tools (identical across every client):
+
+- `bank_getByHostname`
+- `bank_get`
+- `bank_getById`
+- `bank_semanticSearch`
+- `bankVote_get`
+- `country_get`
+- `country_getByCountryCode`
+- `story_get`
+- `story_getById`
+- `world_getOverview`
+- `search_get`
+
+Full descriptions live on the [main MCP page](./README.md).