MCP

MCP Quickstart

Build a mental model first, then expose one small capability through an MCP server and call it from a client.

1. Choose one capability

Start with a narrow action that has clear inputs and outputs. Avoid building a giant "do everything" server on the first pass.

Good first capabilitySearch a documentation index, fetch one record, validate a file, create a ticket, or summarize a known dataset.

Bad first capabilityFull database admin, unrestricted shell access, vague "manage project" tools, or broad account control.

2. Define the contract

Before writing code, define the tool name, description, input schema, result shape, and error behavior. The client and model rely on this contract to decide how to call the capability.

tool: search_docs
description: Search indexed documentation and return the most relevant pages.

input:
  query: string
  limit: number

output:
  results:
    - title: string
      url: string
      snippet: string

3. Implement the server

The server owns the real integration. It validates input, calls the backing system, applies permission rules, and returns structured output.

Keep each tool focused on one job.
Validate inputs before touching external systems.
Return useful errors, not raw stack traces.
Log tool calls in a way that can be audited later.

// server.js
const docs = [
  { title: "MCP Overview", url: "/mcp", text: "MCP connects AI clients to tools and data." },
  { title: "Skill Overview", url: "/skill", text: "Skills package reusable task expertise." },
  { title: "MCP vs Skill", url: "/compare/mcp-vs-skill", text: "MCP is access. Skill is procedure." }
]

export function searchDocs({ query, limit = 3 }) {
  if (!query || typeof query !== "string") {
    return {
      error: {
        code: "INVALID_QUERY",
        message: "query must be a non-empty string",
        retryable: false
      }
    }
  }

  const q = query.toLowerCase()
  return {
    results: docs
      .filter((doc) => `${doc.title} ${doc.text}`.toLowerCase().includes(q))
      .slice(0, limit)
      .map(({ title, url, text }) => ({ title, url, snippet: text }))
  }
}

4. Connect a client

The client discovers the server, exposes available capabilities to the agent, and decides when a tool call is appropriate for the user's task.

Beginner rule If you cannot explain why the agent should call the capability, the capability description is probably not specific enough.

5. Verify the workflow

Test discovery, invocation, result handling, and failure cases. A working happy path is not enough.

Discovery

The client can see the tool name, description, and input schema.

Invocation

The client sends valid structured input and the server handles invalid input safely.

Result

The returned data is clear enough for the agent to use without guessing.

6. Manual practice

Copy this tiny harness to call the example capability without any framework. The point is to understand the contract before adding real MCP SDK code.

// practice.js
import { searchDocs } from "./server.js"

console.log(searchDocs({ query: "MCP", limit: 2 }))
console.log(searchDocs({ query: "", limit: 2 }))

{
  "results": [
    {
      "title": "MCP Overview",
      "url": "/mcp",
      "snippet": "MCP connects AI clients to tools and data."
    },
    {
      "title": "MCP vs Skill",
      "url": "/compare/mcp-vs-skill",
      "snippet": "MCP is access. Skill is procedure."
    }
  ]
}