> For the complete documentation index, see [llms.txt](https://docs.tessl.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tessl.io/creating-skills-and-plugins/add-an-mcp-server.md).

# Add an MCP server

{% hint style="info" %}
**Takeaway** Bundle an MCP server in a plugin when the agent needs a live capability, a tool or a data source, rather than instructions. Declare it in a `.mcp.json` at the plugin root; on install, Tessl materializes it into each agent's native MCP config.
{% endhint %}

A skill gives an agent instructions. An MCP (Model Context Protocol) server gives it a tool or data at runtime: query an internal feature-flag service, look up your component library, fetch a live API schema from staging. Add one only when the plugin genuinely needs a capability the agent does not already have. If the job is "tell the agent how to do X", that is a skill, not an MCP server.

{% hint style="info" %}
This is also available through your agent: `tessl install tessl/plugin-creator`
{% endhint %}

## Declare the server

Point the manifest at a bundled `.mcp.json` file:

```json
{
  "mcpServers": ".mcp.json"
}
```

The value is the literal `".mcp.json"` or `"./.mcp.json"`. Declaring it is optional: the file is discovered by convention at the plugin root either way, so the field just lets you be explicit. The file declares the servers the plugin ships, in two transports:

```json
{
  "mcpServers": {
    "feature-flags": {
      "type": "http",
      "url": "https://flags.internal.engteam.example/mcp"
    },
    "schema-linter": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@engteam/schema-linter-mcp"]
    }
  }
}
```

* **`http`** - a remote server at a URL (http or https), with optional `headers`.
* **`stdio`** - a local server Tessl launches, with a `command` and optional `args` and `env`.

Do not hard-code secrets in `.mcp.json`. If a server needs credentials, reference them from the environment rather than committing them.

## What happens on install

Each agent configures MCP servers in its own way, and that is exactly the work Tessl does for you. When someone installs the plugin, Tessl reads the bundled `.mcp.json` and writes the servers into each agent's own MCP configuration, adapting the shape to that agent. A server declared once is available in Claude Code, Cursor, and other supported agents, without the author writing per-agent config.

## Validate

Lint the plugin, then confirm the servers materialize by installing into a throwaway project and checking the agent's MCP config:

```bash
tessl plugin lint ./api-conventions
tessl install file:./api-conventions
```

For the local development loop, see [Develop and test locally](/creating-skills-and-plugins/develop-and-test-locally.md).

## Next

* [Create a plugin](/creating-skills-and-plugins/create-a-plugin.md) - the plugin that holds the server.
* [Develop and test locally](/creating-skills-and-plugins/develop-and-test-locally.md) - install and confirm the server appears.
* [Publish and update](/creating-skills-and-plugins/publish-and-update.md) - share the plugin once the server works.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.tessl.io/creating-skills-and-plugins/add-an-mcp-server.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.