Building Your First MCP Tool (2026)

Last updated: April 17, 2026

The Model Context Protocol (MCP) has become the standard for connecting Claude Code to external tools and services. Whether you want to integrate with databases, project management tools, or custom APIs, MCP provides a structured way to extend Claude Code’s capabilities. This guide walks you through building your first MCP tool integration from scratch.

What is MCP and Why It Matters in 2026

MCP serves as a bridge between Claude Code and external systems. Unlike traditional API integrations that require custom code for each connection, MCP provides a standardized protocol that Claude Code understands natively. This means you can connect to databases, file systems, GitHub, Slack, and hundreds of other services without writing boilerplate code.

The protocol works through a client-server architecture. Claude Code acts as the MCP client, connecting to servers you configure (see the MCP configuration guide for setup details).

Prerequisites for Building Your First Integration

Before creating your MCP tool integration, ensure your environment is ready. You’ll need Claude Code installed (version 1.0 or later), Node.js 18 or higher, and basic familiarity with your terminal. Check your versions:

claude --version # Should be 1.0 or higher
node --version # Should be 18.0.0 or higher

Create a dedicated directory for your MCP configuration:

mkdir -p ~/mcp-integrations
cd ~/mcp-integrations

Creating Your First MCP Server

The simplest way to start is by building a basic stdio-based MCP server. This server will expose a custom tool that Claude Code can invoke. Create a file named my-first-server.js:

#!/usr/bin/env node

const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
const { CallToolRequestSchema } = require('@modelcontextprotocol/sdk/types.js');
const server = new Server({
 name: 'my-first-mcp-server',
 version: '1.0.0'
}, {
 capabilities: {
 tools: {}
 }
});
server.setRequestHandler(CallToolRequestSchema, async (request) => {
 const { name, arguments: args } = request.params;
 
 if (name === 'greet') {
 return {
 content: [{
 type: 'text',
 text: `Hello, ${args.name}! Welcome to MCP integration.`
 }]
 };
 }
 
 throw new Error(`Unknown tool: ${name}`);
});
async function main() {
 const transport = new StdioServerTransport();
 await server.connect(transport);
}
main().catch(console.error);

This server exposes a single tool called greet that takes a name parameter and returns a personalized greeting.

Configuring Claude Code to Use Your MCP Server

Now you need to tell Claude Code about your new server. Create a configuration file in your Claude settings directory:

mkdir -p ~/.claude

Add your server configuration to ~/.claude/settings.json (or create it if it doesn’t exist):

{
 "mcpServers": {
 "my-first-server": {
 "command": "node",
 "args": ["/Users/yourusername/mcp-integrations/my-first-server.js"]
 }
 }
}

Restart Claude Code, and your server will be available. Test it by asking:

/my-first-server greet Claude

Claude will invoke your custom tool and return the greeting.

Connecting to Real-World Services

The real power of MCP comes from integrating with actual services. Let’s connect to a practical example, a GitHub MCP server that lets Claude interact with repositories.

Many popular services already have MCP server implementations available. For example, the GitHub MCP server enables repository management, issue tracking, and pull request workflows. Install it using npm:

npm install -g @modelcontextprotocol/server-github

Configure it in your settings:

{
 "mcpServers": {
 "github": {
 "command": "npx",
 "args": ["-y", "@modelcontextprotocol/server-github"]
 }
 }
}

Once configured, you can ask Claude Code to perform GitHub operations:

/github list repositories in my account

/github create issue "Fix login bug" on repository my-project

/github summarize open pull requests

Connecting to Production Services

Beyond local stdio connections, MCP servers can run as persistent services using different transport types. The protocol supports three primary connection methods: stdio (standard input/output) for local processes, SSE (Server-Sent Events) for remote servers, and WebSocket for bidirectional communication. SSE and WebSocket suit production deployments where servers run independently.

Here’s a configuration for an SSE-based server alongside a memory service:

{
 "mcpServers": {
 "database": {
 "url": "http://localhost:3000/sse",
 "transport": "sse"
 },
 "memory": {
 "command": "npx",
 "args": ["-y", "@supermemory/mcp-server"],
 "env": {
 "SUPERMEMORY_API_KEY": "your-api-key"
 }
 }
 }
}

This approach works well for databases, API gateways, and microservices that need to stay running between Claude Code sessions.

Building a Custom Skill for MCP Integration

While MCP servers provide the technical connection, Claude Code skills provide the conversational interface. Skills let you define how Claude should interact with your MCP tools.

Create a skill file at ~/.claude/skills/github-assistant.md:

---
name: github-assistant
description: Assistant for GitHub operations via MCP
---
GitHub Assistant
You have access to GitHub MCP tools. Use them to help users with repository management.
Available Tools

- list_repositories: List all repositories for the authenticated user
- create_issue: Create a new issue on a repository
- get_pull_requests: Get open pull requests
- create_pull_request: Create a new pull request
Guidelines

- Always confirm dangerous operations (deleting, merging) before executing
- Provide clear summaries of what each operation will do
- Format repository and issue lists in readable markdown

Now you can invoke this skill:

/github-assistant show me my recent repositories and summarize any open PRs

Integrating with Project Management Tools

Another powerful integration connects Claude Code to project management systems. The Linear MCP server, for example, lets you manage issues and sprints directly from Claude.

Install and configure the Linear MCP server:

npm install -g @linear/mcp-server

Configure in settings:

{
 "mcpServers": {
 "linear": {
 "command": "npx",
 "args": ["-y", "@linear/mcp-server"],
 "env": {
 "LINEAR_API_KEY": "your-api-key-here"
 }
 }
 }
}

Now you can manage issues through conversation:

/linear create issue "Implement user authentication" with priority high

/linear list all issues assigned to me in the current sprint

Using Claude Skills with MCP Servers

Many built-in Claude skills work directly with MCP servers to create powerful combined workflows. The pdf skill can process documents retrieved through MCP tools. The xlsx skill handles spreadsheet operations on data fetched from external sources. The webapp-testing skill validates frontend behavior while MCP servers provide test data.

For example, combine the tdd skill with a database MCP server to generate tests against live data fixtures:

// MCP server provides test data
const testData = await mcp.callTool('database', 'fetchUsers', { limit: 10 });
// tdd skill generates appropriate test cases
describe('UserService', () => {
 testData.forEach(user => {
 it(`should handle user ${user.id}`, async () => {
 const result = await UserService.process(user);
 expect(result.success).toBe(true);
 });
 });
});

This pattern, MCP servers for data access, skills for workflow guidance, is the foundation of productive Claude Code setups.

Best Practices for MCP Integration

When building MCP integrations in 2026, follow these best practices:

Security First: Never commit API keys to version control. Use environment variables and secret management tools. The MCP protocol supports OAuth 2.0 for secure authentication flows.

Error Handling: Implement solid error handling in your MCP servers. Return meaningful error messages that Claude can relay to users:

try {
 // Your logic here
} catch (error) {
 return {
 content: [{
 type: 'text',
 text: `Error: ${error.message}`
 }],
 isError: true
 };
}

Tool Naming: Use clear, descriptive names for your MCP tools. Claude uses these names to determine which tool to invoke, verbose names like create_github_issue_with_labels work better than create_issue.

Progressive Disclosure: Start with a simple integration and expand gradually. Test each new tool before adding more complexity.

Troubleshooting Common Issues

When your MCP integration isn’t working, check these common problems:

Server Not Starting: Verify the command and path in your configuration are correct. Run the server manually to see error output.

Authentication Failures: Ensure your API keys are valid and have the necessary permissions. Many services require specific OAuth scopes.

Tool Not Found: Check that your server’s tool definitions match what you’re calling. Tool names are case-sensitive.

Timeout Issues: For long-running operations, implement async handling and consider adding progress indicators.

Next Steps for Your Integration

claude mcp list command guide — How to use the claude mcp list command to manage MCP servers Now that you’ve built your first MCP integration, explore these advanced topics:
Custom Resources: Expose data beyond tools using MCP’s resource system
Prompts: Create reusable prompt templates for common workflows
Sampling: Enable Claude to run multi-step operations with user confirmation
Multiple Servers: Orchestrate multiple MCP servers for complex workflows

The MCP ecosystem continues growing in 2026, with new servers appearing regularly. Check the official MCP registry for community-contributed integrations, or build your own to connect to internal systems specific to your organization.

Try it: Paste your error into our Error Diagnostic for an instant fix.

I hit this exact error six months ago. Then I wrote a CLAUDE.md that tells Claude my stack, my conventions, and my error handling patterns. Haven't seen it since. I run 5 Claude Max subs, 16 Chrome extensions serving 50K users, and bill $500K+ on Upwork. These CLAUDE.md templates are what I actually use. Not theory — production configs. **[Grab the templates — $99 once, free forever →](https://zovo.one/lifetime?utm_source=ccg&utm_medium=cta-mcp&utm_campaign=building-your-first-mcp-tool-integration-guide-2026)** 47/500 founding spots. Price goes up when they're gone.