MCP Server: The Complete Guide for Developers (2026)

MCP server searches have crossed 60,000 per month and are still climbing. If you're building with AI agents in 2026, you've already hit MCP in Cursor's settings panel, Claude Desktop's config file, or a GitHub README. What you might not have is a clear, practical mental model for what an MCP server actually is, when to use one, and how to build your own.

This guide gives you that. We'll cover the protocol itself, the current ecosystem, the 18 tools Cosmic's native MCP server exposes, and a walkthrough of connecting it to Claude Desktop and Cursor. By the end, you'll have a working MCP-powered content workflow and a solid foundation for building custom MCP servers on top of any data source.

What Is an MCP Server?

MCP stands for Model Context Protocol. An MCP server is a lightweight service that exposes tools, resources, and prompt templates to AI agents in a standardized way.

The key word is standardized. Before MCP, every tool integration for an AI agent required custom glue code: a bespoke JSON schema, a one-off API wrapper, a pile of system prompt instructions. Each AI client had its own format. Nothing was portable.

MCP solves that with a common interface that any compliant AI client can speak. You build the server once. Claude, Cursor, Copilot, Codex — any client that supports MCP can connect to it without modification.

At its core, an MCP server does three things:

• Exposes tools the agent can call ("fetch this object", "create a new page", "search posts by tag")
• Provides resources that give the agent context (a knowledge base, a content schema, a list of available types)
• Accepts prompt templates that shape how the agent reasons about the data it receives

The protocol was introduced by Anthropic and has since been adopted broadly across the developer ecosystem. It operates over two transports: HTTP/SSE (for hosted endpoints) and stdio (for local processes). Any language or runtime can implement it.

Why MCP Is Everywhere Right Now

Three things converged over the last 12 months to push MCP from niche spec to mainstream standard.

1. Agentic IDEs needed a universal tool layer

Cursor, Claude Code, and Codex aren't autocomplete tools anymore. They're autonomous coding agents that run multi-step tasks: reading files, editing code, running tests, committing changes. For those agents to act on your data — your CMS, your database, your API — they need a standardized way to reach it. MCP servers are that hook.

2. Claude's native MCP support changed the calculus

When Anthropic built MCP support directly into Claude Desktop and the Claude API, adoption exploded. Developers who had been wiring up custom tool definitions switched to MCP because the portability payoff was immediate: build the server once, connect any compatible client.

3. The skills model is winning

Early agentic tooling required developers to describe every tool in a flat JSON schema, which didn't scale. MCP introduces the concept of discrete, composable capabilities that agents can discover and invoke dynamically. This is a better mental model for production agentic workflows, and it's the direction the ecosystem has converged on.

The MCP Protocol: How It Actually Works

Under the hood, an MCP server runs as a process (local or hosted) that communicates with MCP clients over a defined protocol.

Transports

MCP supports two transports:

HTTP/SSE (Server-Sent Events): The client sends HTTP POST requests to the server's endpoint. The server streams responses back via SSE. This is the standard for hosted MCP servers — it works over any HTTPS connection, requires no local install, and scales like any other web service.

stdio: The client spawns the server as a local process and communicates over standard input/output. This is common for developer tools that run inside an IDE (Cursor, Claude Desktop in local mode). Lower latency, but requires the server to be installed locally.

The Three Primitives

Tools are functions the agent can call. Each tool has a name, a description (used by the agent to decide when to call it), and a JSON schema for its input parameters. The agent calls a tool, the server executes the function and returns a result, the agent uses the result in its next step.

Resources are data objects the server exposes for context. A resource might be a list of available content types, a brand guideline document, or a schema definition. Resources are read by the agent at the start of a session to build its understanding of what it's working with.

Prompt templates are reusable instruction fragments that shape agent behavior for specific tasks. A template might define how the agent should format a content update request, or how it should structure a search query.

Discovery

When an MCP client first connects to a server, it calls the , , and endpoints. The server returns its full capability manifest. The client caches this and presents the tools to the agent as available functions. No manual configuration required.

The Current MCP Ecosystem

As of mid-2026, MCP servers exist for most major developer tools and data sources. Some of the most actively used:

Content and data:

• Cosmic (content management — read, write, schema, AI generation)
• Notion, Airtable, Linear (structured data and project management)
• GitHub (repositories, issues, PRs)
• Postgres, SQLite (direct database access)

Development tools:

• Vercel (deployments, logs, environment variables)
• Sentry (error tracking)
• Datadog (observability)

Communication:

• Slack (channels, messages, threads)
• Gmail, Outlook (email)

Search and web:

• Brave Search, Exa (web search)
• Firecrawl (web scraping and extraction)

The Anthropic MCP repository maintains an official list of servers: github.com/modelcontextprotocol/servers.

MCP Server vs. Direct API: When to Use Each

MCP is not a replacement for your REST API. It's a layer on top of it, optimized for agent consumption.

Use the REST API directly when:

• You're writing application code that calls an endpoint on a fixed schedule
• You need low-level control over request parameters
• You're integrating with a non-AI system
• You want typed SDK methods with autocomplete and error handling

Use an MCP server when:

• You want an AI agent to discover and call tools dynamically
• You're connecting an AI assistant (Claude, Cursor, Copilot) to your data
• You want portability across multiple AI clients without rewriting integrations
• You're building a workflow where the agent decides which tools to call based on context

For Cosmic specifically: use the TypeScript SDK in your application code, and use the MCP server for agent-driven workflows in Claude Desktop, Cursor, or any MCP-compatible client.

Cosmic's MCP Server: 18 Tools Across 4 Categories

Cosmic ships a native MCP server as a first-class feature. It's not a community plugin — it's built and maintained by the Cosmic team and exposes 18 tools across four categories.

Objects (5 tools)

• — list or search content objects by type, status, or locale
• — fetch a single object by ID or slug
• — create a new object (blog post, page, product, etc.)
• — edit an existing object's content or metadata
• — permanently delete an object

Media (4 tools)

• — browse media files, optionally scoped to a folder
• — fetch metadata and the imgix URL for a single asset
• — upload a file from a URL or base64 payload
• — remove a media file

Object Types (5 tools)

• — list every content model in the bucket
• — fetch the full schema for a single type
• — define a new content model
• — evolve an existing schema
• — drop a content model and all its objects

AI Generation (4 tools)

• — draft, rewrite, summarize, or translate copy using your bucket's own content as context
• — generate an image and store it in your media library
• — generate a short video clip (Google Veo)
• — generate narration audio from text (13 voices via OpenAI TTS)

Connecting Cosmic's MCP Server to Claude Desktop

The hosted endpoint is the fastest way to connect. No local install required.

Step 1: Get your Cosmic credentials

In your Cosmic dashboard, go to your bucket and navigate to Settings > API Access. Copy:

• Your bucket slug
• Your read key
• Your write key (only needed if you want the agent to create or update content)

Step 2: Add to Claude Desktop config

Open your Claude Desktop config file. On macOS it's at .

Add the Cosmic MCP server entry:

For read-only access, omit the header. Write tools will return a clear error if called without it.

Step 3: Restart Claude Desktop

Quit and reopen Claude Desktop. You should see the Cosmic tools appear in the tool picker (the hammer icon in the input bar).

Step 4: Test with a natural language command

Claude will call with type , status , and return the results in a structured format.

Connecting to Cursor

For Cursor, add the config to in your project root (project-scoped) or (global):

Once connected, Cursor's agent can reference your content model when generating code, ensuring that component props, TypeScript types, and API calls match your actual bucket schema.

Self-Hosted Option (stdio)

If you prefer to run the MCP server locally inside your dev environment, the npm package ships a stdio binary:

Or install globally:

The stdio binary reads credentials from environment variables:

Claude Desktop config for self-hosted stdio:

Using the Cosmic SDK in Your Application Code

For application code, use the TypeScript SDK rather than the MCP server. The SDK gives you full type safety, autocomplete, and direct control over every API parameter.

The SDK is the right choice when you control the call site. The MCP server is the right choice when an AI agent controls the call site.

MCP Server vs. Agent Skills: What's the Difference?

Cosmic ships both an MCP server and Agent Skills. These are complementary but serve different purposes.

Use both together: Agent Skills helps your AI write application code that uses the Cosmic SDK correctly; the MCP server lets your AI directly manage content in your bucket.

Building Your Own MCP Server

The Cosmic MCP server is a useful reference for building your own. The core pattern is straightforward:

1. Define your tools as functions with JSON Schema input definitions
2. Implement the endpoint that returns your tool manifest
3. Implement the endpoint that routes calls to your functions and returns results
4. Deploy as an HTTPS endpoint (HTTP/SSE transport) or publish as an npm package (stdio transport)

The MCP TypeScript SDK (@modelcontextprotocol/sdk) handles the protocol boilerplate so you can focus on your tool implementations.

A minimal MCP server in TypeScript looks like this:

This is the foundation. From here you add tools, resources, and prompt templates to match whatever your service exposes.

What to Read Next

Now that you have the full picture on MCP servers, here are the related pieces worth reading:

• What is an MCP Server? (Quick intro) — the short version for sharing with non-technical teammates
• Cosmic MCP vs. Strapi MCP — side-by-side comparison of the two MCP implementations
• MCP vs. Agent Skills — when to use each, with concrete examples
• Build a DevOps Slack Agent with Cosmic — a practical agent tutorial that uses MCP-powered content access

---

Get Started with Cosmic's MCP Server

MCP is moving fast. The developers who wire up production-grade MCP workflows now will have a meaningful head start.

Cosmic's hosted MCP endpoint removes the infrastructure work and lets you focus on what the agent actually does.

Sign up free — no credit card required

Already have an account? Go to MCP settings

Want a walkthrough for your specific stack? Book 15 minutes with Tony

Full MCP docs: cosmicjs.com/docs/mcp-server

Cosmic is a YC W19-backed headless CMS built for developers and AI-native teams.