VibeBase MCP Server

An MCP (Model Context Protocol) server implementation using the official @modelcontextprotocol/sdk that enables Claude Desktop to interact with the VibeBase database API.

Canonical service endpoints:

• Gateway: https://gateway.vibebase.app (agent onboarding + service token exchange)
• API (MCP DB tools): https://api.vibebase.app
• Discovery: https://vibebase.app/api or https://vibebase.app/.well-known/agent.json

Quick Start

# Using npx (recommended)
npx -y @vibebase/mcp-client --api-key vb_your_api_key_here

# Or install globally
npm install -g @vibebase/mcp-client
vibebase-mcp --api-key vb_your_api_key_here --api-url https://api.vibebase.app

Note: This package implements an MCP server (not a client). Claude Desktop is the MCP client that launches this server.

What Is This?

This is an MCP server implementation that Claude Desktop launches locally. It uses the official @modelcontextprotocol/sdk to implement the Model Context Protocol and communicates with the VibeBase backend API via HTTP.

Architecture:

• Claude Desktop = MCP Client (built-in)
• This Package = MCP Server (local process using official SDK)
• VibeBase API = Backend REST API (cloud-hosted)

Claude Desktop (MCP Client) → VibeBase MCP Server (this package) → VibeBase REST API
       stdio                      Official SDK                    HTTP

Key Features:

• ✅ Uses official @modelcontextprotocol/sdk for guaranteed protocol compliance
• ✅ Written in TypeScript for type safety
• ✅ Communicates with Claude Desktop via stdio
• ✅ Makes HTTP calls to VibeBase backend API
• ✅ Provides 10 database tools (create_table, insert_record, etc.)

Installation

Option 1: Use with npx (Recommended)

No installation required! Just use npx:

npx -y @vibebase/mcp-client --api-key vb_your_api_key_here

Option 2: Install Globally

npm install -g @vibebase/mcp-client
vibebase-mcp --api-key vb_your_api_key_here

Option 3: Use Locally with Node

Clone the repo and reference the script directly in your Claude Desktop config.

CLI Usage

The MCP client supports both CLI arguments and environment variables.

CLI Arguments

vibebase-mcp [options]

Options:
  --api-url, --url <url>    VibeBase API URL
  --api-key, --key <key>    VibeBase API key
  -h, --help                Display help message
  -v, --version             Display version

Examples:
  # Using CLI arguments
  vibebase-mcp --api-key vb_xxx --api-url https://api.vibebase.app

  # Using environment variables
  VIBEBASE_API_KEY=vb_xxx vibebase-mcp

  # Mix both (CLI takes precedence)
  VIBEBASE_API_URL=https://api.vibebase.app vibebase-mcp --api-key vb_xxx

Configuration Priority

1. CLI arguments (highest priority)
2. Environment variables
3. Default values (lowest priority)

Claude Desktop Configuration

Step 1: Get Your API Key

1. Sign up at https://vibebase.app
2. Copy your API key from the success page

Step 2: Configure Claude Desktop

Edit your Claude Desktop config file:

Mac/Linux: ~/.config/claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Option A: Using npx with CLI arguments (Recommended)

{
  "mcpServers": {
    "vibebase": {
      "command": "npx",
      "args": [
        "-y",
        "@vibebase/mcp-client",
        "--api-key",
        "vb_your_api_key_here",
        "--api-url",
        "https://api.vibebase.app"
      ]
    }
  }
}

Option B: Using environment variables

{
  "mcpServers": {
    "vibebase": {
      "command": "npx",
      "args": ["-y", "@vibebase/mcp-client"],
      "env": {
        "VIBEBASE_API_KEY": "vb_your_api_key_here",
        "VIBEBASE_API_URL": "https://api.vibebase.app"
      }
    }
  }
}

Option C: Using global installation

{
  "mcpServers": {
    "vibebase": {
      "command": "vibebase-mcp",
      "args": ["--api-key", "vb_your_api_key_here"],
      "env": {
        "VIBEBASE_API_URL": "https://api.vibebase.app"
      }
    }
  }
}

Option D: Using local script with Node

{
  "mcpServers": {
    "vibebase": {
      "command": "node",
      "args": [
        "/absolute/path/to/vibebase-mono/packages/mcp-client/index.js",
        "--api-key",
        "vb_your_api_key_here"
      ],
      "env": {
        "VIBEBASE_API_URL": "https://api.vibebase.app"
      }
    }
  }
}

Important:

• Replace vb_your_api_key_here with your actual API key
• For production, use https://api.vibebase.app
• For development, use https://api-dev.vibebase.app

Step 3: Restart Claude Desktop

Completely quit and reopen Claude Desktop to load the MCP server.

Usage

Once configured, you can use VibeBase directly in Claude Desktop:

Create a table:

"Create a todos table with title and status columns"

Insert data:

"Add a todo: 'Buy groceries' with status 'pending'"

Query data:

"Show me all todos"

Update records:

"Mark the 'Buy groceries' todo as completed"

Configuration Reference

CLI Arguments

| Argument | Alias | Description | Required | |----------|-------|-------------|----------| | --api-key | --key | Your VibeBase API key | ✅ Yes | | --api-url | --url | VibeBase API URL | No | | --help | -h | Display help message | No | | --version | -v | Display version | No |

Environment Variables

| Variable | Description | Default | Overridden By | |----------|-------------|---------|---------------| | VIBEBASE_API_KEY | Your VibeBase API key | None | --api-key | | VIBEBASE_API_URL | VibeBase API URL | https://api.vibebase.app | --api-url | | DEBUG | Enable debug logging (outputs to stderr) | false | --debug |

Troubleshooting

"Error: VIBEBASE_API_KEY is required"

Make sure you've provided the API key via:

• CLI argument: --api-key vb_xxx
• Environment variable: VIBEBASE_API_KEY=vb_xxx
• Or in the env section of your Claude Desktop config

"Claude Desktop doesn't see VibeBase"

1. Check the config file path is correct
2. Verify JSON syntax (no trailing commas)
3. Make sure you've restarted Claude Desktop
4. Check the path to index.js is absolute and correct

"ENOENT: no such file or directory"

The path to index.js must be an absolute path, not a relative path.

Wrong: "args": ["./mcp-client/index.js"]
Correct: "args": ["/Users/yourname/projects/vibebase-mono/mcp-client/index.js"]

Testing the Client Manually

You can test the client directly:

Using environment variables:

export VIBEBASE_API_KEY="vb_your_key"
export VIBEBASE_API_URL="https://vibebase-api-dev.solitary-mode-3b63.workers.dev"
echo '{"jsonrpc":"2.0","id":1,"method":"initialize"}' | node index.js

Using CLI arguments:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize"}' | \
  node index.js --api-key vb_your_key --api-url https://vibebase-api-dev.solitary-mode-3b63.workers.dev

Using npx:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize"}' | \
  npx -y @vibebase/mcp-client --api-key vb_your_key

With debug logging:

DEBUG=1 echo '{"jsonrpc":"2.0","id":1,"method":"initialize"}' | \
  node index.js --api-key vb_your_key

You should see a JSON-RPC response.

How It Works

This package is an MCP Server that implements the official Model Context Protocol:

1. Claude Desktop (MCP Client) launches this server as a local process
2. Communication happens via stdio using the MCP protocol (JSON-RPC 2.0)
3. Official SDK (@modelcontextprotocol/sdk) handles all protocol details
4. When tools are called, this server makes HTTP requests to VibeBase REST API
5. Results are returned to Claude Desktop in MCP format

Under the Hood

// Server creation using official SDK
const server = new Server(
  { name: 'VibeBase', version: '2.0.0' },
  { capabilities: { tools: {} } }
);

// Stdio transport for Claude Desktop
const transport = new StdioServerTransport();
await server.connect(transport);

// Tool handlers call backend API
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const result = await apiClient.createTable(args.name, args.columns);
  return { content: [{ type: 'text', text: JSON.stringify(result) }] };
});

All communication follows the MCP specification.

Available Tools

The MCP client exposes these tools to Claude:

• create_table - Create a new database table
• list_tables - List all your tables
• insert_record - Insert a single record
• batch_insert_records - Insert multiple records
• query_records - Query records with filtering and pagination
• get_record - Get a specific record by ID
• update_record - Update a record
• delete_record - Delete a record
• delete_table - Delete a table
• get_stats - Get your usage statistics

Requirements

• Node.js 18 or higher
• A VibeBase account and API key
• Claude Desktop (MCP client)

Dependencies

• @modelcontextprotocol/sdk - Official MCP SDK from Anthropic
• TypeScript 5.5+ (dev dependency)

Development

This is a TypeScript project using the official MCP SDK.

Build

cd packages/mcp-client
bun install
bun run build

Run in Development Mode

# Using tsx for live TypeScript execution
bun run dev -- --api-key vb_test --api-url http://localhost:8787

# Or test the built version
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | \
  node dist/index.js --api-key vb_test

Debug Mode

# Enable debug logging
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | \
  node dist/index.js --api-key vb_test --debug

# Or in Claude Desktop config
{
  "mcpServers": {
    "vibebase": {
      "command": "npx",
      "args": ["-y", "@vibebase/mcp-client", "--api-key", "vb_xxx", "--debug"]
    }
  }
}

Debug mode outputs detailed logs to stderr:

• Server initialization
• Request/response flow
• Tool calls and API interactions
• Error details

Project Structure

packages/mcp-client/
├── src/
│   ├── index.ts       # Main MCP server (SDK-based)
│   ├── tools.ts       # Tool definitions
│   └── api-client.ts  # Backend API client
├── dist/              # Compiled JavaScript
├── tsconfig.json      # TypeScript configuration
└── package.json       # Package configuration

Production vs Development

Production (Recommended)

{
  "mcpServers": {
    "vibebase": {
      "command": "npx",
      "args": [
        "-y",
        "@vibebase/mcp-client",
        "--api-key",
        "vb_your_production_key",
        "--api-url",
        "https://api.vibebase.app"
      ]
    }
  }
}

Development

{
  "mcpServers": {
    "vibebase": {
      "command": "npx",
      "args": [
        "-y",
        "@vibebase/mcp-client",
        "--api-key",
        "vb_your_dev_key",
        "--api-url",
        "https://vibebase-api-dev.solitary-mode-3b63.workers.dev"
      ]
    }
  }
}

Support

• Documentation: https://docs.vibebase.app
• Issues: https://github.com/yourusername/vibebase/issues
• Discord: https://discord.gg/vibebase

License

MIT