Back to Explore
GuideVibeFix editorialUpdated Nov 20, 2026

Plug your own project in: build your first MCP server from scratch

Your agent can see your project's code but cannot reach its data. An MCP server is the wire that fixes that: three small tools — search, add, update — let the agent work with your database under your approval. Build one from scratch with the official quickstart.

A black USB cable plugged into the side of a silver laptop, a close-up of the connection

Let me draw the boundary of this guide first. The site already has articles about calling other people's APIs, such as "API Resilience: Circuit Breakers and Retries" and "Webhooks Integration", plus several search guides. This guide is not about "how to call someone else's API" — it is the reverse: package your own data and features as tools, hand them to the agent, and let it operate them directly for you. Calling an API means going out to others; an MCP server means opening a crack in your own back door and letting the agent walk in to work. Also, this round carries a companion guide on this site, "Stop pasting the same instructions ten times: write your agent a SKILL.md skill pack". The two are partners: a skill pack is the instruction manual you hand the agent, and an MCP server is the lever that lets it actually do things. The manual says when and in what order to work; the lever lets it move things for real.

The "Little Bookshelf" used below is a fictional practice project: a small personal book-collection app built with AI help, with a frontend, a backend, and a database. All the code and configuration built around it are simplified for explanation, not production code you can run as-is. Every rule, version number, and interface name about the MCP protocol comes from the official MCP documentation, cited at the end.

The agent can see it, but cannot reach it

Check the symptoms first. Your "Little Bookshelf" is running, and the books live in your own database. One day you ask the agent to tidy up your collection: "list the books I bought this year that I have not finished". The agent says "sure" — and then asks: where is the data? Export it as a file and send it to me? So you export a CSV from the database, paste it into the conversation, and repeat "bought this year, not finished". Next time you want to add a book, you open the admin panel and fill in the form yourself. The agent can see your code but cannot reach your data, and you are forever stuck in the middle as the person doing the copy-pasting.

Two common workarounds both have flaws. The first is exporting the data and pasting it in every time. Once the data grows, it no longer fits, and what you paste is a snapshot: after the agent "adds" a book, the real database has not changed, and you still have to go and change it yourself. The second is giving the agent direct database access and writing the credentials into the prompt. That is like taping your house key to the front door: the agent can work, but it can also wipe the database by accident, and the password sits in the chat history.

What is missing is not "a smarter model" but a wire: a standard, controlled channel for the agent to read and write your data. That wire is an MCP server. You write a tiny server that exposes exactly the three things you want the agent to do as tools: search books, add a book, change a reading status. When the agent needs them, it calls them itself, while you watch what it called and what it changed. No data exports, no passwords in chat history, and the scope of what it can do is exactly the three tools you exposed — not one more.

MCP in one sentence: USB-C for AI

The official documentation's metaphor is a good one: MCP is the USB-C port for AI applications. Before, every external system needed its own custom integration, like every device needing its own charging cable; with a standard port, you build once and plug in anywhere. MCP is an open standard, not one company's private protocol — Claude, ChatGPT, VS Code, Cursor, and other clients all support it, so a server you write once can be used by many clients.

Let us sort out the roles with a picture first. Three parties are involved. The Host is the AI application you use, such as Claude Desktop or Claude Code. The Client is the part inside the Host that speaks MCP. The Server is the small server you write. The Client inside the Host connects to your Server, and your Server touches your data and systems. The agent never touches your database directly; it talks to the Client, and the Client talks to the Server following the protocol. The messages on that wire are JSON-RPC — in plain terms, a fixed format for "call my tool, I return a result".

A server can offer three capabilities, the official trio. Tools are "functions that can be called", like searching or adding a book, usually with your approval before the call. Resources are "file-like data that can be read", such as a book list or a configuration file. Prompts are "pre-written templates" that help a user phrase a task, such as the standard wording for "tidy up the collection". This guide covers Tools only, because for a vibe project Tools are the first thing you use and the most useful. Once one tool works, adding Resources and Prompts later is easy.

One common misunderstanding needs correcting first: an MCP server is not "yet another backend service". It does not handle user login, page rendering, or scheduled jobs. It does exactly one thing: it hands a few operations you chose to the agent in a standard format. Your "Little Bookshelf" backend stays exactly as it is; the MCP server is just a thin translation layer sitting next to it.

MCP architecture: the Client inside the Host (Claude Desktop / Claude Code) connects over JSON-RPC to the MCP server you write, which exposes only three tools — search books, add a book, change status — and the server then talks to your database

The diagram above is what this guide builds: the agent's Host on the left, the Client in the middle, your server on the right, and your database behind the server. Two doors sit between the agent and the database: the Client only speaks the protocol, and the server only exposes the three tools you approved.

Pick a language first, then a transport

Before writing code, settle two choices, both spelled out in the official quickstart.

The first choice: which language to write it in. The official quickstart ships in eight languages — Python, TypeScript, Java, Kotlin, C#, Ruby, Rust, Go — and the logic is the same in all of them: build a server, expose two tools, connect it to a client and test it. For a vibe project, pick the language your project already uses: "Little Bookshelf" has a Python backend, so write it in Python — Python 3.10 or higher, MCP Python SDK 2.0.0 or higher, with uv to set up the project. If your project is TypeScript, use the TypeScript version with Node.js 20 or higher. The language is only the shell; the protocol is the same, so pick the one that feels easy.

The second choice: how the server and the client talk to each other. Two transports exist: stdio and Streamable HTTP. Stdio means "start it locally, talk over pipes": the client launches your server process and the two exchange messages through standard input and output. Streamable HTTP means "run it as a service on the network": the server is deployed at some address and the client connects over HTTP. When you start, stdio is enough. The server runs on your own machine, the agent calls it from the same environment, and there is no deployment, no domain name, and no public-internet security to think about. Only when the agent is not on the same machine, or several people need to use it, should you consider HTTP.

Choosing stdio comes with one rule that must be burned into memory — the official docs repeat it in every language version: a stdio server must never write logs to standard output. The messages themselves travel over standard output, so one printed log line corrupts the messages and kills the server on the spot. In Python, do not use print; in TypeScript, do not use console.log. Send logs to standard error instead: Python's logging module writes to stderr by default, and TypeScript has console.error. HTTP servers have no such restriction, because messages travel in HTTP responses rather than standard output.

Build your first server from scratch: three tools are enough

The official quickstart builds a weather server exposing two tools, get_alerts and get_forecast: one checks weather alerts, the other checks the forecast, using the public API of the US National Weather Service. Adapt it slightly and it becomes the "Little Bookshelf" version: search_books to search books, add_book to add a book, update_status to change a reading status. Three tools, reads first and writes second.

Start with the skeleton. Following the official steps, create the project with uv and install the mcp package, and the server code is actually short: create an MCPServer instance named little-bookshelf, then register the tools one by one. The Python SDK has a thoughtful touch: a tool's definition is generated directly from the function's type hints and docstring. Write an ordinary function, spell out the parameter types and a one-sentence description, and the tool's input format is generated automatically. No hand-written JSON Schema, and one fewer place for things to disagree.

How to write a tool — one example. search_books takes two parameters: query, the keyword to search for, and status, the reading status such as "want to read", "reading", or "finished" — leave it out and it searches everything. Inside, the function queries the database and returns the results as human-readable text. The key is that one docstring sentence: "Search the collection by keyword and reading status." The agent decides when to call the tool from that sentence alone. The more specific the description, the more accurate the calls: "search the collection by keyword and reading status" beats "search the collection", and "manage books" is far worse — the agent has no idea what the tool actually does.

Three taboos apply to tool descriptions. First, do not write them like titles: "Book management tool". Second, do not cram every capability into one tool: "manage the collection, including search, add, edit, and delete". One tool does one job; three tools are three tools, and merging them into one almighty tool to save effort is a false economy. Third, do not hide side effects in the description: a tool called search_books that secretly edits the database will make the agent afraid to call it next time. Name, description, and actual behavior must agree — that rule matters more than any trick.

add_book and update_status are write operations, so think one step further: what happens when the agent passes a wrong parameter? A book with an empty title, or a status value that does not exist. The good practice is to validate inside the tool: an empty title returns "the title cannot be empty, please check again"; a status outside "want to read / reading / finished" returns "status must be one of want to read, reading, finished". Do not wait for the database to throw an error and hand the agent a pile of English error text. Tool error messages are read by the agent — write them in plain language so it can correct itself and try again.

Before starting the server, run through a mental checklist: are there exactly three tools, with no extra one slipped in; can someone who has never seen the code guess what each tool does from its description; do the write operations validate input and return plain-language errors; is there any print or console.log writing to standard output anywhere? Pass the whole list, then start it.

Plug it into a client and call it yourself

Writing the server is not the end. Connecting it to a client and calling it with your own hands is what makes it real. The official docs use Claude Desktop as the example: open the configuration file claude_desktop_config.json, add an entry under mcpServers named little-bookshelf, with the launch command — uv, which directory, which file to run. Save it and restart Claude Desktop. If the configuration is right, an MCP entry appears in the interface, listing the three tools you registered.

Paths are the easiest thing to get wrong in that configuration. The official docs stress using absolute paths: the path after uv --directory must be the absolute path of the server folder, not a relative one. A relative path works in your own terminal and breaks under a different launch method. Before restarting the client, run the launch command by hand in the terminal and check that the server starts cleanly instead of erroring out immediately. If it runs by hand, then configure the client.

A useful tool for verification is the Inspector. The official docs mention the Inspector CLI, which can list a server's tools and actually call one to see what comes back. Call all three tools in the Inspector first: search_books with a keyword and check the returned list; add_book with a fake book and check the database really gained a row; update_status to mark that fake book "finished", then search again to confirm the status changed. Once all three work, try natural language in the client: "add The Three-Body Problem to the collection, status reading." If the agent calls add_book with the right parameters and the database gains a row, the wire is live.

One version detail is worth knowing, spelled out in the TypeScript quickstart: a modern server should be started with serveStdio, which negotiates the protocol version with each client, so both 2026-07-28 clients and clients still on the 2025-era handshake can connect. If you still wire it by hand with server.connect(new StdioServerTransport()), the server only serves 2025-era clients. Using the current SDK and following the latest official instructions means you do not have to think about this. The Inspector also has protocol eras: it defaults to the legacy era, which only exercises the 2025 handshake, so run the same command again with --protocol-era modern to confirm new clients can list your tools too. Only when both eras list all three tools is compatibility real.

Three traps you will hit

The first trap is logs in the wrong place. It was stated above and bears repeating, because it is the most common way beginners kill a server: anything a stdio server writes to standard output corrupts the messages. Python's print, TypeScript's console.log, and the startup banner some libraries print to standard output by default are all suspects. The symptom is distinctive: the server runs fine by hand in the terminal, but the moment a client connects, it drops and no tool list appears. Check where the logs go first — nine times out of ten, that is it.

The second trap is a badly written tool description. When the agent decides which tool to call, it reads almost nothing but the name and the description. Name three tools manage_books, manage_books_v2, and manage_books_new, or describe them all as "handles collection-related operations", and the agent can only guess. A wrong guess calls the wrong tool and edits the wrong data, and you clean up after it. The fix is simple: start names with verbs — search_books, add_book, update_status — and write descriptions that say "what goes in, what comes out, when to use it". After writing them, ask someone who has never seen the code to read them; if they can guess what each tool does, the descriptions pass.

The third trap is thinking about permissions and security too late. Once a tool is exposed, the agent can call it — and can also call it wrong and change your data. Write operations should respect three lines: first, read-only first. Expose read operations like search_books first, get them running smoothly, and only then add add_book and update_status. A miscalled read returns a pile of wrong data; a miscalled write really changes your database. Second, write operations go through user approval. MCP is designed so that tool calls ask for approval first — do not switch the approval off to save clicks. Third, secrets and passwords never go into the repository, the skill description, or the tool description. The server needs to connect to the database, so put the connection string in an environment variable or a local configuration file; the code reads the variable and never contains the secret in plain text.

On security, the official docs have a dedicated security section worth reading on its own. The core idea is one sentence: every tool a server exposes is a power you personally hand to the agent. Keep the list of powers as short as possible, the permissions as small as possible, and the audit trail as clear as possible. Before adding a new tool, ask one question: what is the worst thing this tool can do? If the answer makes you sweat, tighten it first.

When to move to HTTP, and when to leave it alone

Once stdio works, many people immediately ask "should I deploy it on the internet?" Not yet. The test is simple: is the only user you, and are the server and the agent on the same machine? If both answers are yes, stdio is enough. Turning it into an HTTP service adds a pile of concerns: a domain name, HTTPS, authentication, who may call it, how often, and where the logs live. For a "Little Bookshelf" that only you use, that cost is pure waste.

When is HTTP actually required? Three cases. First, the agent is not on your machine — for example, you use a web client that needs to reach a server at your home. Second, several people need to use it, such as a team sharing one collection MCP server. Third, the server itself must stay online so others can reach it any time. At that point the transport changes to Streamable HTTP, writing logs to standard output stops being a problem — but the security checklist doubles: who may connect, what authentication, whether each tool call needs approval, and how long call records are kept. The official security section covers all of it; follow it, do not invent your own.

There is one more case where the right answer is to walk away: the system you want to expose should never be touched by an agent at all. Write access to a production database, a payment API that can actually spend money, an admin panel that can delete users — these are not problems an MCP server solves. They are openings that should never have been made. The right design adds another layer in between: expose only a tool that "files a request for the operation", and a human still clicks the button that really executes it. The agent can fill in the request form for you, but money and data still need a human nod.

Start by getting one tool working

If you want to start today, the checklist is five steps, and one evening is enough to get through it:

One, pick the language. Use the language your project already uses — Python for a Python project, TypeScript for a TypeScript one — and do not spend time learning a new language for this. Two, build only one read tool. Start with search_books and nothing else. A miscalled read has no consequences, which makes it the safest practice run. Three, connect it to a client. Call it once in the Inspector, call it once in natural language in Claude Desktop — only when both work does it count as working. Four, add the write tools. Add add_book and update_status one at a time, with validation and plain-language error messages included. Five, commit the configuration to the repository. Server code, launch command, and a sample configuration all go in, so the next machine or the next person can redo it from scratch.

Once one tool works, something becomes clear: the sheet of paper between the agent and your own project was always thin. What you were missing was never a stronger model — it was a compliant wire. With the wire connected, the agent stops being a bystander that can only read code and becomes a partner that can look up data, change state, and run procedures for you. And all you have to do is write down, in three tools, what it is allowed to do — and stay able to take it back at any time.

Sources: Model Context Protocol official documentation, "What is the Model Context Protocol?" (https://modelcontextprotocol.io/docs/getting-started/intro, read 2026-11-17; page updated 2026-11-09); "Build an MCP server" quickstart (https://modelcontextprotocol.io/quickstart/server, read 2026-11-17, Python and TypeScript editions); for the skill-pack side, see this site's companion guide "Stop pasting the same instructions ten times: write your agent a SKILL.md skill pack".

Views 2Comments 0

Comments (0)

ME
0/1000
Loading comments...

Sources

Browse projectsPublish your project

Related articles

Real photo: hands typing on a MacBook Pro showing JavaScript code that changes HTML content, with a white mouse, papers, and binders on a white desk
Guide
Functions without the confusion: JavaScript functions, parameters, and arrow functions, explained plainly

You already call functions every day; this guide names what you have been doing. Following MDN's Functions, Arrow function expressions, and Rest parameters: declarations versus expressions, parameters and arguments, default values, rest parameters, spread syntax, return values, arrow function shorthand, the this trap, callbacks, and scope.

Tool TipsFrontend EngineeringAI Coding
Real photo: a Casio scientific calculator on a wooden desk showing 123456789 + 987654321 = 1111111110, beside handwritten math notebooks, a pen, a mug, and a laptop edge
Guide
Don't let 0.1 + 0.2 break your bill: JavaScript numbers and Math, explained plainly

Numbers in JavaScript are one type, Number, stored as 64-bit floats — which is why 0.1 + 0.2 is 0.30000000000000004. This guide follows MDN's Basic math in JavaScript, Math, and Number: one number type, float error, counting money in cents, converting strings, NaN and Infinity, safe integers, the four rounding methods, Math.random, the Math toolbox, and formatting for display.

Tool TipsFrontend EngineeringAI Coding
Real photo: a woman in an office sticking colorful sticky notes in rows on a white wall, holding a pink note in her hand
Guide
Stop shimming with margins: Flexbox one-dimensional layout, explained plainly

Flexbox lays things out in one direction at a time, and when it is done right, the nav bar, the card wall, and the cart rows all behave. This guide follows MDN's Basic concepts of flexbox, Aligning items in a flex container, and Controlling ratios of flex items along the main axis: the two axes, containers and items, direction and wrapping, free space, the three flex properties, alignment on both axes, and gaps and auto margins.

Developer WorkflowFrontend EngineeringAI Coding