What is an MCP server? A plain-English guide with a real example

An MCP server is a small service that gives an AI assistant new abilities through one shared protocol, the Model Context Protocol. The server describes a list of tools (actions like “upload a file” or “search tickets”), and any MCP-compatible app, such as Claude, Cursor or VS Code, can discover those tools and call them when you ask. Think of it as a plug: build the server once, and every assistant that speaks MCP can use it.

This guide explains the moving parts in plain English, then walks through a real, live server: the one we run at linkinseconds.com, which lets an assistant publish files as public links.

The problem MCP solves

Language models are good at reading and writing, but on their own they cannot do anything in the world. They cannot open your ticket tracker, query a database or upload a file. For a while, every app solved this its own way: a plugin format here, a custom function-calling setup there. A company that wanted its service available in five assistants had to build five integrations.

MCP, introduced by Anthropic in late 2024 as an open protocol, replaces that with one standard. The assistant side is called the client (or host). The service side is the server. As long as both speak MCP, they work together.

The three building blocks

An MCP server can offer three kinds of things:

• Tools. Actions the model can decide to call, like upload_file or create_issue. This is what most servers are about.
• Resources. Data the client can read, like a file or a database row, identified by a URI.
• Prompts. Ready-made prompt templates a user can pick, such as “summarise this pull request”.

Our server only offers tools. That is common: if the job is “do something”, tools are all you need.

What a tool looks like

A tool is a name, a plain-language description and a JSON Schema for its inputs. The description matters more than you might think, because the model reads it to decide when to use the tool. Here is a shortened version of one of ours:

{
  "name": "upload_file",
  "title": "Upload a file and get a link",
  "description": "Publish a file and get a public Link in Seconds URL ...",
  "inputSchema": {
    "type": "object",
    "properties": {
      "filename": { "type": "string" },
      "content": { "type": "string" },
      "content_base64": { "type": "string" },
      "title": { "type": "string" }
    },
    "required": ["filename"]
  }
}

When you say “publish this page as a link”, the model sees that description, fills in filename and content, and asks the client to call the tool. Most clients ask you to approve the call first.

How the conversation works

Under the hood, MCP messages are JSON-RPC 2.0: small JSON objects with a method, some params and an id. A typical session uses three methods:

1. initialize. The client and server agree on a protocol version and say what they support.
2. tools/list. The client asks which tools exist and gets back their names, descriptions and schemas.
3. tools/call. The client runs one tool with arguments and gets back a result.

Here is a real tools/call against our server, sent with curl. Normally your AI client sends this for you.

curl -s -X POST https://linkinseconds.com/api/mcp \
  -H "Authorization: Bearer lis_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "upload_file",
      "arguments": { "filename": "hello.html", "content": "<h1>Hello</h1>" }
    }
  }'

And the answer:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      { "type": "text", "text": "Published: https://linkinseconds.com/p/hello-x4" }
    ],
    "structuredContent": {
      "slug": "hello-x4",
      "title": "hello",
      "url": "https://linkinseconds.com/p/hello-x4"
    }
  }
}

The content part is text for the model to read and pass on to you. The structuredContent part is the same answer as data, which is handy when the assistant needs the URL for a next step.

Transports: local or remote

MCP messages can travel two ways:

Streamable HTTP replaced an older HTTP plus Server-Sent Events transport. A server can stream responses back when it needs to, but it does not have to. Ours is stateless: every request is a single POST that gets a single JSON answer. There are no sessions to keep alive and nothing to reconnect, which makes it easy to run on serverless hosting.

Authentication: who is calling?

A local stdio server runs as you, so it usually needs no login. A remote server needs to know which account a request belongs to. The MCP spec describes an OAuth-based flow for this, and some servers use it. Many, including ours, use something simpler: an API key sent in a header.

For our server, you create a key in your dashboard (it starts with lis_) and your client sends it as Authorization: Bearer lis_... on every request. The server never accepts browser cookies, so a web page cannot trigger uploads on your behalf. We store only a hash of the key, and you can delete it at any time. See Authentication and API keys.

A real example: the Link in Seconds MCP server

Here is the whole server in one list:

• URL: https://linkinseconds.com/api/mcp
• Transport: Streamable HTTP, stateless, JSON responses
• Auth: Authorization: Bearer with an API key
• Tools: upload_file (inline, up to 3 MB), create_upload_url and finish_upload (bigger files, sent straight to storage), and list_links

Clients can also find it without being told: we publish a server card at /.well-known/mcp/server-card.json that lists the URL, transport, required header and tools. More on that in Agent discovery files, and in our case study Is your site agent-ready?

How to connect one

Every client needs the same two things: the server URL and, for a remote server, how to authenticate. In Claude Code it is one command:

claude mcp add --transport http linkinseconds https://linkinseconds.com/api/mcp \
  --header "Authorization: Bearer lis_YOUR_KEY"

Cursor and VS Code use a small JSON file instead. Step by step instructions for each are in How to let Claude publish files as links and in the MCP server docs.

Common questions

Is an MCP server the same as an API?

Close, but not quite. An API is built for programmers, who read the docs and write code. An MCP server is built for AI clients, which read tool descriptions and decide on their own when to call them. Many services offer both. We do: the MCP tools and our upload API share the same code underneath.

Is it safe to connect MCP servers?

Treat a server like any app you install. Connect ones you trust, give each its own key, approve tool calls you do not expect, and remember that a tool can do whatever its description says, such as making a file public.

Do I need to code to use one?

No. Using a server is configuration: paste a URL and a key. Building one takes code, but a tools-only server can be surprisingly small. All the tool details for ours are in the MCP tools reference, and more guides live under AI agents and developers.