An MCP server is a small program that shows an AI app your files, databases and services under the rules of the Model Context Protocol. Claude Code starts it, asks what it can do, and then lets the model call those functions as tools. This article goes in order: how the pieces fit, how to connect a ready-made server, how to write your own, and what to check before you run code you did not write.
MCP server in plain words
MCP stands for Model Context Protocol. Anthropic introduced it on 25 November 2024 as an open standard that connects AI assistants to the systems where data lives (Anthropic announcement). The protocol docs compare it to USB-C: one port fits many devices, so nobody needs a separate cable for each. Claude, ChatGPT, VS Code and Cursor already support MCP.
Before MCP, every app wrote its own glue for every service. Now a service exposes its capabilities once as an MCP server, and any compatible client discovers them on its own.
There are three roles (protocol architecture):
| Role | What it is | Example |
|---|---|---|
| Host | An AI app that manages the connections | Claude Code, Claude Desktop, VS Code |
| Client | A component inside the host, one per server | Created by the host automatically |
| Server | A program that supplies context and actions | A filesystem server, a Sentry server |
Messages travel as JSON-RPC 2.0 over one of two transports:
- stdio. The host launches the server as a child process on your machine. No network is involved, and one server talks to one client.
- Streamable HTTP. The server lives at a URL and serves many clients. It accepts bearer tokens, API keys and OAuth.
As of 29 October 2026, the current revision of the specification on the protocol site is 2026-07-28.
Three kinds of capabilities: tools, resources, prompts
A server offers a client three kinds of capabilities. These are the names you will meet in SDKs and configs.
| Primitive | What it does | Example |
|---|---|---|
| Tools | Functions the model calls: an API request, a search, a write | search_notes |
| Resources | Data for context: a file, a database row, an API response | notes://ideas |
| Prompts | Ready-made prompt templates for the model | "Summarize this week's notes" |
To the model, all of this looks like ordinary tools. The client fetches the list through tools/list and invokes one through tools/call. The model never talks to MCP itself: the host intercepts the call and goes to the server on its behalf.
A handy rule: if an action changes data, make it a tool. If it only hands data over, make it a resource. The client then shows up front which parts are risky.
Connecting an MCP server to Claude Code and Claude Desktop
In Claude Code one command is enough. The double dash separates the flags of claude itself from the command that starts the server (Claude Code MCP docs):
claude mcp add <name> -- <command> [args]
claude mcp add --transport http <name> <url>
claude mcp list
The first line adds a local (stdio) server, the second a remote one, and the third lists servers and their connection state. Inside a session, /mcp does the same.
The --scope flag decides where the setting is stored:
| Scope | Stored in | Visible to |
|---|---|---|
local (default) | ~/.claude.json, tied to the project | Only you |
project | .mcp.json in the project root | The whole team through git |
user | ~/.claude.json | You, in every project |
Claude Code asks you to approve project-scope servers in an interactive session, so a .mcp.json from someone else will not start silently. The file looks like this:
{
"mcpServers": {
"shared-server": {
"type": "http",
"url": "https://example.com/mcp"
}
}
}
Claude Desktop reads servers from claude_desktop_config.json: on macOS the file is in ~/Library/Application Support/Claude/, on Windows in %AppData%\Claude\. It needs an mcpServers key, and the app has to be restarted after you edit it. Use absolute paths to the server. If the app cannot find uv, put the full path to it in the config (which uv on macOS and Linux, where uv on Windows). The install and config steps are covered in Claude Desktop: install and connect MCP, and setting the app up with codexkey is described in the Claude Desktop guide.
How to write your own MCP server in Python
The example below searches for a string in the .md notes in the ~/notes folder. We ran the code on Python SDK 2.3.0: the server starts over stdio, the tool finds a note, and the resource returns its text. The SDK needs Python 3.11 or newer (python-sdk repository).
uv init notes-mcp
cd notes-mcp
uv add "mcp[cli]"
The server.py file:
from pathlib import Path
from mcp.server import MCPServer
NOTES_DIR = Path.home() / "notes"
mcp = MCPServer("notes")
@mcp.tool()
def search_notes(query: str) -> str:
"""Find .md notes that contain the string query. Return the file and the first matching line."""
hits = []
for path in sorted(NOTES_DIR.glob("*.md")):
for line in path.read_text(encoding="utf-8").splitlines():
if query.lower() in line.lower():
hits.append(f"{path.name}: {line.strip()}")
break
return "\n".join(hits) or "Nothing found"
@mcp.resource("notes://{name}")
def read_note(name: str) -> str:
"""Text of a note by file name without the extension."""
path = (NOTES_DIR / f"{name}.md").resolve()
if not path.is_relative_to(NOTES_DIR.resolve()):
raise ValueError("Path outside the notes folder")
return path.read_text(encoding="utf-8")
if __name__ == "__main__":
mcp.run(transport="stdio")
You do not write the argument schema separately. The query: str type becomes JSON Schema, and the docstring becomes the tool description that the model reads. Word the docstring as instructions for a person who sees nothing else.
First we test the server without an AI:
uv run mcp dev server.py
This opens MCP Inspector, a web interface where you call tools by hand (it needs Node.js). When the answers look right, connect the server:
claude mcp add notes -- uv --directory /absolute/path/to/notes-mcp run server.py
Now you can ask Claude Code in a session to "find everything about MCP in my notes", and the model will call search_notes. For a remote setup, run uv run mcp run server.py --transport streamable-http: the server answers at http://localhost:8000/mcp, and you connect it with claude mcp add --transport http notes http://localhost:8000/mcp.
Three traps at the start:
- A stdio server must never call
print(). Standard output carries the JSON-RPC messages, and one strayprintbreaks the connection. Log through theloggingmodule, which writes to stderr. - Older tutorials use
from mcp.server.fastmcp import FastMCP. In SDK 2.x the class is renamed toMCPServer, and the old import fails withModuleNotFoundError. Write it the new way or pinmcp<2. - The name in the
notes://{name}resource comes from the model. Without theis_relative_tocheck, a string containing..would escape the notes folder.
We cover the TypeScript version, remote deployment and a comparison of transports in the practical guide to MCP servers for Claude, so we do not repeat them here.
Ready-made MCP servers: what to pick, what is free, what exists for 1C
The protocol and the SDK are free. You pay for the service the server talks to: an API, a database or a cloud. There is no ranking of the "best MCP servers" outside a specific task, so we look at four signs: the service owner publishes the server, the code is open, the permissions are minimal, and the repository is alive.
Where to look:
modelcontextprotocol/serverson GitHub. It holds the reference servers Everything, Fetch, Filesystem, Git, Memory, Sequential Thinking and Time. The README warns that these are teaching examples, not production solutions.- Thirteen servers, including GitHub, GitLab, PostgreSQL, Redis, Sentry, Slack and SQLite, moved to an archive repository and are mostly no longer maintained.
- The registry of published servers: registry.modelcontextprotocol.io.
We found no official MCP server for 1C (the Russian business software platform), but there are open community projects. One of them, alkoleft/mcp-bsl-platform-context, gives the AI reference material on the platform's syntax and object model. It is written in Kotlin under the MIT license, needs Java 17 or newer, works over stdio or SSE, and recommends 1C platform 8.3.20 or later. We did not check how active the repository is, so look at the commit dates before connecting it. Preparing the configurations themselves for Claude is covered in vibe coding for 1C with Claude.
MCP when you work through codexkey
MCP lives on the client side, and the gateway sits on the model side. Claude Code connects to MCP servers as usual, while requests to the model go to https://api.codexkey.online (without /v1) with your sk_cdx_... key:
export ANTHROPIC_BASE_URL="https://api.codexkey.online"
export ANTHROPIC_AUTH_TOKEN="sk_cdx_YOUR_KEY"
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-5-5[1m]"
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-5[1m]"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-sonnet-5"
claude
The ANTHROPIC_DEFAULT_* lines are required: without them Claude Code asks for its own default models and answers "There's an issue with the selected model". The full settings.json is in the Claude Code guide, and models and prices are on the models page. You do not need to sign in to an Anthropic account. You can pay with a card issued in Russia, through SBP (the Russian Faster Payments System) or with crypto. To start from zero, follow the Claude Code setup in Russia. For the question of which model to pick for agent work, see the best AI for programming in 2026. If vibe coding is new to you, read what vibe coding is first.
One consequence that not everyone remembers: tool descriptions and tool call results become part of the request context. Everything a tool returns to the model, for example the text of a file it read, goes to the provider together with the rest of the prompt.
Security: which MCP servers are safe to run
A local MCP server runs with the rights of your user. The MCP security guide names the risks outright: arbitrary command execution, data loss and a malicious launch command hidden in a config (security best practices). The Claude Code docs add that servers which pull in external content open a path for prompt injection.
Our rules:
- Read the launch command in full before you add someone else's server.
npx something && curl ...on one line is a reason to stop. - Start with read-only servers and enable writing and deleting as a separate step.
- Pass keys through
--envor environment variables, and do not commit them to.mcp.json. - In your own server, validate every argument, restrict directories and keep secrets out of resources: the model reads them.
- For remote servers, use tokens with minimal rights. The specification forbids a server from accepting tokens that were not issued for it.
FAQ
What is an MCP server in plain words?
A program that hands an AI app files, database data and actions (tools) under one common rule, the same for every client. You do not need a separate integration per service: you connect a ready-made server once, and Claude Code, Claude Desktop or VS Code can see what it offers.
How do I connect an MCP server to Claude Code?
Add a local server with claude mcp add <name> -- <launch command> and a remote one with claude mcp add --transport http <name> <url>. To check the result, run claude mcp list in the terminal or /mcp inside a session.
How do I build an MCP server myself?
Install the SDK (for Python, uv add "mcp[cli]"), create an MCPServer, put the @mcp.tool() and @mcp.resource() decorators on your functions and start the server with the stdio transport. Before connecting it to an AI, you can test it with uv run mcp dev server.py.
Do free MCP servers exist?
Yes, the reference servers and most community servers are open. Only the code is free, though: you pay the owner for access to a third-party API, database or cloud. Before installing, check the license, the activity of the repository and the permissions it asks for.
Is there an MCP server for 1C?
Open community projects exist, for example alkoleft/mcp-bsl-platform-context with platform reference material. We found no official server from the vendor as of 29 October 2026. Do not connect such servers to a working database without checking the code and the license.
Does MCP work when Claude Code is connected through codexkey?
Yes. MCP works on the client side, so the gateway does not get in its way: servers are connected with claude mcp add, and requests to the model go through codexkey. Remember that tool call results end up in the prompt and go to the model provider.
Is it safe to install other people's MCP servers?
Only after you check them. A local server runs with your rights and can execute arbitrary commands. Read the launch command and the code, grant minimal rights, and keep secrets in environment variables, not in the repository.