BPBluePages
List a Skill
← Back to Blog
MCPClaudeAI ToolsTutorialBluePages

How to Add Custom MCP Tools to Claude Desktop

By BluePages Team·April 2, 2026·5 min read

The Model Context Protocol (MCP) turns Claude from a chat assistant into a tool-using agent. By connecting MCP servers, you give Claude the ability to search databases, call APIs, read files, execute code, and interact with external services -- all from within the chat interface.

This guide walks through the complete setup process, using the BluePages MCP server as a concrete example.

What Is an MCP Server?

An MCP server is a lightweight process that exposes tools to AI assistants via a standardized protocol. Each tool has a name, a description, and a typed schema for its inputs. When Claude determines that a tool would help answer your question, it calls the MCP server, which executes the action and returns the result.

The architecture:

Claude Desktop <--stdio--> MCP Server Process <--HTTP/SDK--> External APIs

Claude Desktop launches MCP servers as child processes and communicates over stdin/stdout. The server handles the actual API calls, data fetching, or computation.

Prerequisites

  • Claude Desktop installed (macOS or Windows)
  • Node.js 18+ (for npm-based MCP servers)
  • A text editor for config files

Step 1: Locate Your Config File

Claude Desktop stores its MCP configuration in a JSON file. The location depends on your platform:

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

If the file does not exist, create it. Start with an empty configuration:

{
  "mcpServers": {}
}

Step 2: Add the BluePages MCP Server

The BluePages MCP server gives Claude the ability to search a directory of AI-callable skills and APIs. Add it to your config:

{
  "mcpServers": {
    "bluepages": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/bluepages-mcp-server"],
      "env": {}
    }
  }
}

That is the entire configuration. The -y flag tells npx to auto-confirm the package installation on first run.

If You Need an API Key

Some MCP servers require authentication. Pass API keys via the env field:

{
  "mcpServers": {
    "bluepages": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/bluepages-mcp-server"],
      "env": {
        "BLUEPAGES_API_KEY": "your-api-key-here"
      }
    }
  }
}

Step 3: Restart Claude Desktop

After saving the config file, completely quit and relaunch Claude Desktop. It reads the configuration at startup, so changes require a restart.

Once restarted, you should see the MCP server tools available in the chat interface. Look for a hammer icon or tool indicator near the text input area.

Step 4: Verify the Connection

Open a new conversation and ask Claude something that would use the BluePages tools:

"Search BluePages for sentiment analysis APIs"

Claude should recognize that this requires the BluePages search tool, invoke it, and return results from the directory. You will see the tool call appear in the conversation, showing the input parameters and the returned data.

If the tool does not appear, check the Claude Desktop logs for errors:

macOS:

cat ~/Library/Logs/Claude/mcp*.log

Common issues:

  • Node.js not found: Make sure node and npx are in your PATH
  • Package not found: Check that the npm package name is correct
  • Permission denied: On macOS, you may need to allow the npx binary in System Preferences > Privacy & Security

Step 5: Add Multiple MCP Servers

You can connect as many MCP servers as you need. Each one adds new capabilities to Claude:

{
  "mcpServers": {
    "bluepages": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/bluepages-mcp-server"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/projects"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    }
  }
}

This configuration gives Claude the ability to:

  • Search for APIs and skills via BluePages
  • Read and write files in your projects directory
  • Interact with GitHub repositories, issues, and pull requests

What Can Claude Do with BluePages Connected?

With the BluePages MCP server active, Claude gains these capabilities:

Search for Skills by Keyword

Ask: "Find me an API that can transcribe audio files"

Claude will search the BluePages directory and return matching skills with descriptions, pricing, and connection details.

Get Skill Details

Ask: "Show me the details for the transcription skill on BluePages"

Claude retrieves the full skill profile including endpoints, authentication requirements, pricing, and usage examples.

Invoke Skills Directly

For skills that support direct invocation, Claude can call them as part of answering your question:

Ask: "Use BluePages to find a summarization API and summarize this text: [your text]"

Claude searches for the capability, identifies the right skill, invokes it, and returns the result -- all in one conversation turn.

Building Your Own MCP Server

If you want to expose your own API as an MCP server, the setup is straightforward with the TypeScript SDK:

npm init -y
npm install @modelcontextprotocol/sdk zod

Create your server:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "my-api",
  version: "1.0.0",
});

server.tool(
  "search_products",
  "Search the product catalog by keyword",
  {
    query: z.string().describe("Search query"),
    limit: z.number().optional().describe("Max results to return"),
  },
  async ({ query, limit = 10 }) => {
    const response = await fetch(
      `https://api.mystore.com/products?q=${encodeURIComponent(query)}&limit=${limit}`
    );
    const data = await response.json();
    return {
      content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
    };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

Add a bin entry to your package.json, publish to npm, and anyone can add your server to their Claude Desktop config.

Troubleshooting

Server starts but no tools appear: Check that your tool definitions have both a description and a valid Zod schema. Claude Desktop silently drops tools with invalid schemas.

Slow startup: The first run with npx downloads the package. Subsequent runs use the cached version. If startup speed matters, install the package globally: npm install -g @anthropic-ai/bluepages-mcp-server and use the global binary path instead of npx.

Server crashes after a few minutes: MCP servers must handle the stdio protocol correctly. Make sure you are not writing to stdout except through the MCP SDK transport. Stray console.log calls will corrupt the protocol stream -- use console.error for debug logging instead.

Next Steps

Start with the BluePages MCP server to give Claude access to a searchable directory of AI-callable APIs. Then explore the MCP server registry for community-built servers covering databases, file systems, browsers, and more.

If you have an API that agents should be able to use, list it on BluePages and consider building an MCP server wrapper. The combination of directory listing and MCP server gives your API maximum reach across the AI assistant ecosystem.

Share this article

Share on XShare on LinkedIn
← Back to all posts