@apiverve/mcp-server 1.0.1 → 1.1.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 APIVerve
+Copyright (c) 2026 APIVerve
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -4,7 +4,7 @@
 
 <img src="https://apiverve.com/images/favicon.png" alt="APIVerve Logo" width="80" />
 
-**249+ APIs accessible through the Model Context Protocol**
+**356+ APIs accessible through the Model Context Protocol**
 
 [![npm version](https://img.shields.io/npm/v/@apiverve/mcp-server)](https://www.npmjs.com/package/@apiverve/mcp-server)
 [![PyPI version](https://img.shields.io/pypi/v/apiverve-mcp)](https://pypi.org/project/apiverve-mcp/)
@@ -17,11 +17,11 @@
 
 ## 🚀 Overview
 
-The **APIVerve MCP Server** provides seamless access to 249+ production-ready APIs through the [Model Context Protocol](https://modelcontextprotocol.io). Connect AI assistants like Claude, ChatGPT, and other MCP-compatible clients to a vast ecosystem of data and functionality.
+The **APIVerve MCP Server** provides seamless access to 356+ production-ready APIs through the [Model Context Protocol](https://modelcontextprotocol.io). Connect AI assistants like Claude, ChatGPT, and other MCP-compatible clients to a vast ecosystem of data and functionality.
 
 ### ✨ Features
 
-- 🎯 **249+ APIs** - Weather, news, geocoding, validation, conversion, and more
+- 🎯 **356+ APIs** - Weather, news, geocoding, validation, conversion, and more
 - 🔐 **OAuth 2.0 Authentication** - Secure, industry-standard authentication
 - 📊 **Token-Based Pricing** - Pay only for what you use
 - 🚀 **High Performance** - Cloud-hosted with 99%+ uptime
@@ -30,94 +30,80 @@ The **APIVerve MCP Server** provides seamless access to 249+ production-ready AP
 
 ## 📦 Installation
 
-### For Claude Desktop / MCP Clients
+APIVerve is a **remote** MCP server — there is nothing to run locally. Point your client at the URL below and it will handle sign-in for you.
 
-Add to your MCP settings file:
+### Quick setup
 
-**Claude Desktop (`claude_desktop_config.json`):**
-```json
-{
-  "mcpServers": {
-    "apiverve": {
-      "type": "sse",
-      "url": "https://api.apiverve.com/v1/mcp"
-    }
-  }
-}
+```bash
+npx @apiverve/mcp-server
+```
+
+Configures VS Code and Cursor, and prints the manual step for Claude Desktop. Target one client with `npx @apiverve/mcp-server cursor`.
+
+For headless setups, pass a key instead of using sign-in:
+
+```bash
+npx @apiverve/mcp-server --api-key YOUR_API_KEY
 ```
 
-**VS Code / Cline:**
+Python users can do the same with `pip install apiverve-mcp` then `apiverve-mcp` (or `apiverve-mcp --api-key YOUR_API_KEY`).
+
+### Manual setup
+
+**Claude Desktop** — remote servers are added through the app, not a config file:
+
+> Settings → Connectors → Add custom connector → `https://api.apiverve.com/v1/mcp`
+
+**VS Code** (`mcp.json`):
 ```json
 {
-  "inputs": [],
   "servers": {
-    "APIVerve": {
-      "type": "sse",
-      "url": "https://api.apiverve.com/v1/mcp",
-      "headers": {}
+    "apiverve": {
+      "type": "http",
+      "url": "https://api.apiverve.com/v1/mcp"
     }
   }
 }
 ```
 
-**Cursor:**
+**Cursor** (`~/.cursor/mcp.json`):
 ```json
 {
   "mcpServers": {
     "apiverve": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-everything"],
-      "env": {
-        "MCP_BRIDGE_URL": "https://api.apiverve.com/v1/mcp"
-      }
+      "url": "https://api.apiverve.com/v1/mcp"
     }
   }
 }
 ```
 
-Or configure directly in Cursor settings (Settings > Features > Model Context Protocol)
-
-### NPM Package
-
-```bash
-npm install -g @apiverve/mcp-server
-```
-
-Then run:
-```bash
-apiverve-mcp install
-```
-
-This will automatically configure your MCP client.
+## 🔑 Authentication
 
-### Python Package
+Two ways in — pick whichever fits:
 
-```bash
-pip install apiverve-mcp
-```
+**OAuth (default, recommended)** — leave the config as shown above. On first use the server returns an authorization challenge and your client walks you through sign-in. No key is stored on disk, and access can be revoked from the dashboard.
 
-```python
-from apiverve_mcp import configure_mcp
+**API key** — add your key as a header. Useful for CI and headless environments where no browser is available:
 
-# Auto-configure MCP client
-configure_mcp()
+```json
+{
+  "mcpServers": {
+    "apiverve": {
+      "url": "https://api.apiverve.com/v1/mcp",
+      "headers": { "x-api-key": "YOUR_API_KEY" }
+    }
+  }
+}
 ```
 
-## 🔑 Authentication
-
-APIVerve uses OAuth 2.0 for secure authentication:
-
-1. **Sign up** at [https://apiverve.com](https://apiverve.com)
-2. **Get your API key** from the dashboard
-3. **Authorize** when prompted by your MCP client
-4. **Start using** 249+ APIs immediately
+Claude Desktop's Custom Connectors cannot send custom headers, so it is OAuth-only.
 
-**Free tier available** - No credit card required to start!
+Get a key at [https://apiverve.com](https://apiverve.com). **Free tier available** — no credit card required to start!
 
 ## 🎯 Available APIs
 
 <details>
-<summary><b>Click to see all 249+ available APIs</b></summary>
+<summary><b>Click to see all 356+ available APIs</b></summary>
 
 ### 🌤️ Weather & Environment
 - Weather Forecast
@@ -185,16 +171,17 @@ Claude: [Uses Currency Converter API]
 
 ### Programmatic Usage (Python)
 
+Connect straight to the remote server — no local process involved:
+
 ```python
-from mcp import ClientSession, StdioServerParameters
-from mcp.client.stdio import stdio_client
+from mcp import ClientSession
+from mcp.client.streamable_http import streamablehttp_client
+
+url = "https://api.apiverve.com/v1/mcp"
+headers = {"x-api-key": "YOUR_API_KEY"}
 
-async with stdio_client(StdioServerParameters(
-    command="apiverve-mcp",
-    args=[]
-)) as (read, write):
+async with streamablehttp_client(url, headers=headers) as (read, write, _):
     async with ClientSession(read, write) as session:
-        # Initialize
         await session.initialize()
 
         # List available tools
@@ -216,17 +203,17 @@ APIVerve uses a flexible token-based pricing model with multiple tiers to fit yo
 
 **[View Pricing Plans →](https://apiverve.com/pricing)**
 
-Token costs vary by API complexity - simple APIs start at 1 token per call.
+Credit costs vary by API complexity - simple APIs start at 1 credit per call.
 
 ## 🛠️ Technical Details
 
 ### Server Information
 
-- **Type**: Server-Sent Events (SSE)
-- **Protocol**: MCP 2024-11-05
-- **Authentication**: OAuth 2.0 with PKCE
+- **Transport**: Streamable HTTP
+- **Protocol**: MCP 2025-06-18 (negotiates down to 2025-03-26 and 2024-11-05)
+- **Authentication**: OAuth 2.0 with PKCE, or `x-api-key` header
 - **Base URL**: `https://api.apiverve.com/v1/mcp`
-- **API Version**: 1.0.1
+- **API Version**: 1.1.0
 
 ### OAuth Endpoints
 

package/bin/install.js

@@ -1,208 +1,149 @@
-#!/usr/bin/env node
-
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-
-const SERVER_CONFIG = {
-  type: 'sse',
-  url: 'https://api.apiverve.com/v1/mcp'
-};
-
-function getClaudeConfigPath() {
-  const platform = os.platform();
-
-  if (platform === 'darwin') {
-    // macOS
-    return path.join(os.homedir(), 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
-  } else if (platform === 'win32') {
-    // Windows
-    return path.join(process.env.APPDATA, 'Claude', 'claude_desktop_config.json');
-  } else {
-    // Linux
-    return path.join(os.homedir(), '.config', 'Claude', 'claude_desktop_config.json');
-  }
-}
-
-function getVSCodeConfigPath() {
-  const platform = os.platform();
-
-  if (platform === 'darwin') {
-    return path.join(os.homedir(), 'Library', 'Application Support', 'Code', 'User', 'settings.json');
-  } else if (platform === 'win32') {
-    return path.join(process.env.APPDATA, 'Code', 'User', 'settings.json');
-  } else {
-    return path.join(os.homedir(), '.config', 'Code', 'User', 'settings.json');
-  }
-}
-
-function getCursorConfigPath() {
-  const platform = os.platform();
-
-  if (platform === 'darwin') {
-    return path.join(os.homedir(), 'Library', 'Application Support', 'Cursor', 'User', 'settings.json');
-  } else if (platform === 'win32') {
-    return path.join(process.env.APPDATA, 'Cursor', 'User', 'settings.json');
-  } else {
-    return path.join(os.homedir(), '.config', 'Cursor', 'User', 'settings.json');
-  }
-}
-
-function ensureDirectoryExists(filePath) {
-  const dir = path.dirname(filePath);
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-  }
-}
-
-function installToClaudeDesktop() {
-  const configPath = getClaudeConfigPath();
-
-  console.log('📍 Claude Desktop config path:', configPath);
-
-  ensureDirectoryExists(configPath);
-
-  let config = {};
-
-  // Read existing config
-  if (fs.existsSync(configPath)) {
-    try {
-      const content = fs.readFileSync(configPath, 'utf8');
-      config = JSON.parse(content);
-    } catch (err) {
-      console.warn('⚠️  Could not parse existing config, creating new one');
-    }
-  }
-
-  // Ensure mcpServers section exists
-  if (!config.mcpServers) {
-    config.mcpServers = {};
-  }
-
-  // Add APIVerve server
-  config.mcpServers.apiverve = SERVER_CONFIG;
-
-  // Write config
-  fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf8');
-
-  console.log('✅ APIVerve MCP server added to Claude Desktop config');
-  return true;
-}
-
-function installToVSCode() {
-  const configPath = getVSCodeConfigPath();
-
-  console.log('📍 VS Code config path:', configPath);
-
-  ensureDirectoryExists(configPath);
-
-  let config = {};
-
-  // Read existing config
-  if (fs.existsSync(configPath)) {
-    try {
-      const content = fs.readFileSync(configPath, 'utf8');
-      config = JSON.parse(content);
-    } catch (err) {
-      console.warn('⚠️  Could not parse existing config, creating new one');
-    }
-  }
-
-  // Ensure mcp section exists (VS Code / Cline extension)
-  if (!config.mcp) {
-    config.mcp = { servers: {} };
-  }
-  if (!config.mcp.servers) {
-    config.mcp.servers = {};
-  }
-
-  // Add APIVerve server
-  config.mcp.servers.APIVerve = {
-    type: 'sse',
-    url: SERVER_CONFIG.url,
-    headers: {}
-  };
-
-  // Write config
-  fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf8');
-
-  console.log('✅ APIVerve MCP server added to VS Code config');
-  return true;
-}
-
-function installToCursor() {
-  const configPath = getCursorConfigPath();
-
-  console.log('📍 Cursor config path:', configPath);
-
-  ensureDirectoryExists(configPath);
-
-  let config = {};
-
-  // Read existing config
-  if (fs.existsSync(configPath)) {
-    try {
-      const content = fs.readFileSync(configPath, 'utf8');
-      config = JSON.parse(content);
-    } catch (err) {
-      console.warn('⚠️  Could not parse existing config, creating new one');
-    }
-  }
-
-  // Ensure mcpServers section exists
-  if (!config.mcpServers) {
-    config.mcpServers = {};
-  }
-
-  // Add APIVerve server
-  config.mcpServers.apiverve = SERVER_CONFIG;
-
-  // Write config
-  fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf8');
-
-  console.log('✅ APIVerve MCP server added to Cursor config');
-  return true;
-}
-
-function main() {
-  console.log('\n🔌 APIVerve MCP Server Installer\n');
-
-  const args = process.argv.slice(2);
-  const target = args[0] || 'all';
-
-  try {
-    if (target === 'claude' || target === 'all') {
-      installToClaudeDesktop();
-    }
-
-    if (target === 'vscode' || target === 'all') {
-      installToVSCode();
-    }
-
-    if (target === 'cursor' || target === 'all') {
-      installToCursor();
-    }
-
-    console.log('\n✨ Installation complete!');
-    console.log('\n📖 Next steps:');
-    console.log('   1. Restart your MCP client (Claude Desktop, VS Code, or Cursor)');
-    console.log('   2. Sign up at https://apiverve.com');
-    console.log('   3. Authorize when prompted');
-    console.log('   4. Start using 249+ APIs!\n');
-  } catch (error) {
-    console.error('\n❌ Installation failed:', error.message);
-    console.error('\n💡 Manual installation:');
-    console.error('   Add this to your MCP client config:\n');
-    console.error('   {');
-    console.error('     "mcpServers": {');
-    console.error('       "apiverve": {');
-    console.error('         "type": "sse",');
-    console.error('         "url": "https://api.apiverve.com/v1/mcp"');
-    console.error('       }');
-    console.error('     }');
-    console.error('   }\n');
-    process.exit(1);
-  }
-}
-
-main();
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const SERVER_URL = 'https://api.apiverve.com/v1/mcp';
+const TARGETS = ['claude', 'vscode', 'cursor', 'all'];
+
+// Auth is negotiated, not configured: with no headers the server answers 401 with a
+// WWW-Authenticate challenge and the client runs OAuth. --api-key skips that for
+// headless setups by sending the key directly instead.
+function parseArgs(argv) {
+  const args = { target: 'all', apiKey: null };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--api-key') {
+      args.apiKey = argv[++i] || null;
+    } else if (argv[i].startsWith('--api-key=')) {
+      args.apiKey = argv[i].slice('--api-key='.length);
+    } else if (!argv[i].startsWith('-')) {
+      args.target = argv[i];
+    }
+  }
+  return args;
+}
+
+function userConfigDir(appName) {
+  const platform = os.platform();
+  if (platform === 'darwin') return path.join(os.homedir(), 'Library', 'Application Support', appName);
+  if (platform === 'win32') return path.join(process.env.APPDATA, appName);
+  return path.join(os.homedir(), '.config', appName);
+}
+
+// VS Code moved MCP config out of settings.json into its own mcp.json.
+function getVSCodeConfigPath() {
+  return path.join(userConfigDir('Code'), 'User', 'mcp.json');
+}
+
+// Cursor reads ~/.cursor/mcp.json, not the app support dir.
+function getCursorConfigPath() {
+  return path.join(os.homedir(), '.cursor', 'mcp.json');
+}
+
+function readJson(filePath) {
+  if (!fs.existsSync(filePath)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (err) {
+    throw new Error(`${filePath} exists but is not valid JSON. Fix or remove it, then re-run.`);
+  }
+}
+
+function writeJson(filePath, data) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf8');
+}
+
+function authHeaders(apiKey) {
+  return apiKey ? { headers: { 'x-api-key': apiKey } } : {};
+}
+
+// Remote servers cannot be added through claude_desktop_config.json — that file is
+// stdio-only. Custom Connectors is the supported path and it is UI-driven, so the most
+// honest thing the installer can do is say so rather than write config Claude ignores.
+function installToClaudeDesktop() {
+  console.log('○ Claude Desktop — manual step required');
+  console.log('  Claude Desktop only accepts remote MCP servers through Custom Connectors,');
+  console.log('  which cannot be configured from a file. Add it in the app:');
+  console.log('');
+  console.log('    Settings → Connectors → Add custom connector');
+  console.log(`    URL: ${SERVER_URL}`);
+  console.log('');
+  console.log('  Claude will prompt you to sign in on first use.');
+  console.log('');
+  return true;
+}
+
+function installToVSCode(apiKey) {
+  const configPath = getVSCodeConfigPath();
+  const config = readJson(configPath);
+
+  if (!config.servers) config.servers = {};
+  config.servers.apiverve = { type: 'http', url: SERVER_URL, ...authHeaders(apiKey) };
+
+  writeJson(configPath, config);
+  console.log(`✅ VS Code configured — ${configPath}`);
+  return true;
+}
+
+function installToCursor(apiKey) {
+  const configPath = getCursorConfigPath();
+  const config = readJson(configPath);
+
+  // Cursor infers the transport from the presence of url; type is for stdio servers only.
+  if (!config.mcpServers) config.mcpServers = {};
+  config.mcpServers.apiverve = { url: SERVER_URL, ...authHeaders(apiKey) };
+
+  writeJson(configPath, config);
+  console.log(`✅ Cursor configured — ${configPath}`);
+  return true;
+}
+
+function printManualConfig() {
+  console.error('\n💡 Configure manually instead:');
+  console.error('');
+  console.error('  VS Code — mcp.json');
+  console.error(`    { "servers": { "apiverve": { "type": "http", "url": "${SERVER_URL}" } } }`);
+  console.error('');
+  console.error('  Cursor — ~/.cursor/mcp.json');
+  console.error(`    { "mcpServers": { "apiverve": { "url": "${SERVER_URL}" } } }`);
+  console.error('');
+  console.error('  Claude Desktop — Settings → Connectors → Add custom connector');
+  console.error(`    ${SERVER_URL}`);
+  console.error('');
+}
+
+function main() {
+  console.log('\n🔌 APIVerve MCP Server Installer\n');
+
+  const { target, apiKey } = parseArgs(process.argv.slice(2));
+
+  // An unrecognised target used to match no branch and exit 0 having done nothing.
+  if (!TARGETS.includes(target)) {
+    console.error(`Unknown target "${target}".`);
+    console.error(`Usage: apiverve-mcp [${TARGETS.join('|')}] [--api-key KEY]\n`);
+    process.exit(1);
+  }
+
+  if (apiKey) {
+    console.log('Using API key auth — the key will be written into the config file.\n');
+  } else {
+    console.log('Using OAuth — no key is stored; your client will prompt you to sign in.\n');
+  }
+
+  try {
+    if (target === 'claude' || target === 'all') installToClaudeDesktop();
+    if (target === 'vscode' || target === 'all') installToVSCode(apiKey);
+    if (target === 'cursor' || target === 'all') installToCursor(apiKey);
+
+    console.log('\n✨ Done. Restart your MCP client to pick up the change.');
+    console.log('   Manage access and API keys at https://apiverve.com\n');
+  } catch (error) {
+    console.error('\n❌ Installation failed:', error.message);
+    printManualConfig();
+    process.exit(1);
+  }
+}
+
+main();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@apiverve/mcp-server",
-  "version": "1.0.1",
-  "description": "APIVerve MCP Server - Access 249+ APIs through the Model Context Protocol",
+  "version": "1.1.0",
+  "description": "APIVerve MCP Server - Access 356+ APIs through the Model Context Protocol",
   "main": "index.js",
   "bin": {
     "apiverve-mcp": "./bin/install.js"
@@ -29,8 +29,13 @@
   },
   "mcpServers": {
     "apiverve": {
-      "type": "sse",
-      "url": "https://api.apiverve.com/v1/mcp"
+      "command": "node",
+      "args": [
+        "./index.js"
+      ],
+      "env": {
+        "APIVERVE_API_KEY": ""
+      }
     }
   }
 }