Skip to content
Ömer Tiryaki (Home)
← All notes

Guidechecked

Connecting MCP servers

How to connect Claude to your own data and tools through the Model Context Protocol, safely and step by step.

What MCP is

MCP is an open standard that lets AI assistants use tools and data. An MCP server exposes functions such as reading files, searching email or creating tasks. Claude calls them when they fit the request. Three roles are involved: the host is the AI application, for example Claude Code. For every server it creates its own client that holds the connection, and the server is the program that provides the tools. A server can offer three kinds of building blocks:

  1. Tools: functions that do something, for example query a database or call an API.
  2. Resources: data to read, such as the contents of a file or a database schema.
  3. Prompts: ready-made templates for recurring tasks.

Tip:A simple picture: MCP is like a standard power socket. Any tool with the right plug works in every application that speaks MCP, without a separate cable for every combination.

Local or remote: the transports

The transport defines how client and server exchange messages. The messages themselves are always the same: JSON-RPC 2.0. With stdio the host starts the server as a program on your computer and talks to it through standard input and standard output. This is fast and needs no network. With Streamable HTTP the server runs somewhere on the network, is reachable through a URL and can serve many clients at once.

Tip:Older guides still mention SSE as a transport. SSE is deprecated, use Streamable HTTP for remote servers.

Prerequisites

Many ready-made servers are started with npx, so you almost always need Node.js. Quickly check the versions in the terminal before you add anything.

  1. Claude Code or the Claude desktop app, up to date.
  2. Node.js (LTS version) for servers that start with npx.
  3. For your own server with the TypeScript SDK: Node.js 20 or later.
  4. For remote servers: the URL and, if required, an account with the provider.
node --version
npx --version

Add it in Claude Code

Claude starts local servers as a program and reaches remote servers through a URL. For local servers two hyphens (--) separate Claude’s options from the server’s start command. Without this separator Claude would read server options such as --port as its own. Pass keys with -e as environment variables, or with --header for remote servers.

# local: files in a folder
claude mcp add files -- npx -y @modelcontextprotocol/server-filesystem ~/Documents

# local with a key as environment variable
claude mcp add -e API_KEY=YOUR_KEY --transport stdio my-service -- npx -y @example/mcp-server

# remote: via a URL
claude mcp add --transport http my-server https://example.com/mcp

# remote with a token in the header
claude mcp add --transport http my-server https://example.com/mcp --header "Authorization: Bearer YOUR_TOKEN"

Tip:Put another option such as --transport stdio between -e and the server name. Otherwise Claude reads the name as another key-value pair.

Scopes and .mcp.json for teams

The scope defines where a server applies and who sees it. Without an option it lands in the local scope: only for you and only in this project. With --scope user it is available in all your projects. Claude stores both in ~/.claude.json. With --scope project Claude writes it to the .mcp.json file in the project folder, which you commit to the repo so the whole team uses the same server.

{
  "mcpServers": {
    "team-api": {
      "type": "http",
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer ${API_KEY}" }
    }
  }
}

Tip:In .mcp.json you can write ${VARIABLE}, also with a default as ${VARIABLE:-value}. That way the real key never ends up in the repo and everyone sets it locally. Before Claude Code uses servers from a .mcp.json, it asks for your approval once.

In the Claude desktop app

The desktop app reads local servers from the file claude_desktop_config.json. On macOS it lives in ~/Library/Application Support/Claude/, on Windows in %APPDATA%\Claude\. Every entry under mcpServers has a name, a command and its arguments (args).

  1. Open the app settings, choose “Developer” on the left and click “Edit Config”.
  2. Add the server under mcpServers and save the file.
  3. Quit the app completely and restart it. Closing the window is not enough.
  4. Check under “Connectors” in the input field that the server and its tools appear.
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/name/Documents"]
    }
  }
}

Caution:Use full, absolute paths, not relative ones. The server runs with your user permissions and can do anything in the shared folders that you can do.

Check and manage

In a running session /mcp shows which servers are connected and which tools they offer. That is also where you sign in to remote servers that require OAuth: Claude opens the browser, stores the token and refreshes it on its own. In the terminal three commands help.

claude mcp list          # all servers and their status
claude mcp get files     # details for one server
claude mcp remove files  # remove a server

Tip:In Claude Code a server’s tools are named mcp__server__tool. Use this name to allow or block them specifically in the permissions.

Staying safe

An MCP server can do everything you allow it to. Local servers run with your user permissions, remote servers see all data Claude sends them. That is why a few fixed rules apply.

  1. Only install servers from trusted sources and take a quick look at the code.
  2. As few permissions as possible: only share the folder that is needed.
  3. Pass keys and tokens as environment variables, never write them into the code.
  4. For tools that change or send something, require confirmation for every action.
  5. Expect prompt injection from servers that load outside content such as web pages, emails or tickets.

Caution:Prompt injection means text inside the loaded data tries to give Claude instructions. So never combine, unchecked, a server that reads outside text with one that sends or deletes without confirmation.

Building your own server

With the official TypeScript SDK you describe every tool with a name, a description and an input schema. The schema validates the input before your code runs and at the same time tells Claude which fields to fill in. The description matters, because Claude uses it to decide when to use the tool. That is how I connected my Life OS to Claude: tasks, appointments and receipts are available right in the chat. Older examples still use the version 1 package @modelcontextprotocol/sdk.

  1. Create a project and mark it as an ES module, because the SDK only ships ES modules.
  2. Install the SDK, zod and tsx. tsx runs TypeScript without a build step.
  3. Write the server in src/index.ts and start it with npx tsx src/index.ts.
  4. Add it in Claude Code, using the full path to the file.
npm init -y
npm pkg set type=module
npm install @modelcontextprotocol/server zod tsx

// src/index.ts
import { McpServer } from '@modelcontextprotocol/server';
import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
import * as z from 'zod/v4';

const server = new McpServer({ name: 'greeting-server', version: '1.0.0' });

server.registerTool(
  'greet',
  {
    description: 'Greets a person by name',
    inputSchema: z.object({ name: z.string() }),
  },
  async ({ name }) => ({
    content: [{ type: 'text', text: `Hello, ${name}!` }],
  }),
);

async function main() {
  await server.connect(new StdioServerTransport());
}
main();

# add it
claude mcp add greeting -- npx tsx /full/path/src/index.ts

Caution:With stdio, standard output is the protocol channel. A single console.log is enough to corrupt the messages. So always log with console.error, which goes to stderr.

Testing with the MCP Inspector

Before you add a server to Claude, it is best to test it with the MCP Inspector. It is a local web app that starts your server and lets you call every tool by hand. That way you see right away whether schema, input and responses are correct, without a model in between.

npx @modelcontextprotocol/inspector npx tsx src/index.ts

Tip:The Inspector works with any stdio server, including third-party ones. That way you can check which tools a server really brings before you add it.

Running it remotely

If a server should be reachable from several devices or for several people, it runs remotely over Streamable HTTP. Cloudflare Workers work well for this: Cloudflare offers a template that serves a server under the path /mcp. Without sign-in anyone with the URL can use it. So for private data, put authentication in front of it. MCP recommends OAuth for this, and Claude Code guides you through the login via /mcp.

# create the template without sign-in
npm create cloudflare@latest -- remote-mcp-server-authless --template=cloudflare/ai/demos/remote-mcp-authless

# test locally at http://localhost:8788/mcp
npm start

# deploy
npx wrangler@latest deploy

# add it in Claude Code
claude mcp add --transport http my-server https://remote-mcp-server-authless.YOUR-ACCOUNT.workers.dev/mcp

Caution:The “authless” template has no sign-in. Use it for learning, but do not connect real data before OAuth or another protection is in place.

Common errors and fixes

Most problems have only a few causes. A good first step is always to run the server’s start command yourself in the terminal. Errors that show up there also stop it from starting in Claude.

  1. Server does not start: test the command in the terminal and check that node and npx are found.
  2. Wrong paths: always use absolute paths in configuration files.
  3. Missing variables: claude mcp list warns when a ${VARIABLE} from .mcp.json is not set.
  4. Broken JSON: one missing comma is enough for the desktop app to load no servers at all.
  5. Change has no effect: quit the desktop app completely and restart it.
  6. Slow start: increase the timeout, for example MCP_TIMEOUT=10000 claude for ten seconds.

Tip:The desktop app writes logs to ~/Library/Logs/Claude on macOS and to %APPDATA%\Claude\logs on Windows. mcp-server-NAME.log contains the error output of that server.

Quick checklist

Before you use a new server for good, go through these points.

  1. Source checked and code or docs read.
  2. Only the necessary folders and permissions shared.
  3. Keys set as environment variables, none of them in the repo.
  4. Suitable scope chosen: local, project or user.
  5. Checked with the Inspector or /mcp that server and tools work.
  6. Tools that write only allowed with confirmation.

More notes

Privacy

No tracking cookies

Nothing about you is collected here.

What your browser remembers

None of it is used for analytics.

Read the privacy policy