# Add an MCP server to Claude Code: what free tools expose

> The current commands to connect a remote MCP server to Claude Code, then what a server's free tools should and should not offer, using our own four.

Published 2026-09-30 · https://aiskills402.com/blog/add-mcp-server-claude-code

Connecting one takes a single command: you give Claude Code a name and the server's address, and once the server connects its tools are available to the agent, in the same session for a remote server. The harder part is on the other side: a server decides what anyone may do with no key and no payment. We show both halves, using our own server at `https://mcp.aiskills402.com/mcp` as the worked example.

Commands change between releases, so everything below about Claude Code comes from [the current MCP documentation](https://code.claude.com/docs/en/mcp) as we read it on 30 September 2026. If your version prints something different, trust the page over this post.

## Connect a remote server

A server that speaks over HTTP is added with the `mcp add` command and the `http` transport:

```
claude mcp add --transport http <name> <url>
```

Ours, for example:

```
claude mcp add --transport http aiskills https://mcp.aiskills402.com/mcp
```

Before we wrote that line we checked the transport against the live server: a plain `initialize` request sent with POST to that address came back as a single event-stream message with the server name `aiskills402` and a tools capability, which is the streamable HTTP style that the `http` flag expects. Your server may differ, so ask its documentation which transport it speaks before choosing the flag.

Three scopes decide who sees the server. The default, local, keeps it private to you in the current project. Project scope writes it to a `.mcp.json` file in the project root so the whole team gets it. User scope makes it available in all your projects. You pick one with `--scope`. The shared file looks like this:

```json
{
  "mcpServers": {
    "aiskills": {
      "type": "http",
      "url": "https://mcp.aiskills402.com/mcp"
    }
  }
}
```

To manage what you added, `claude mcp list` shows everything, `claude mcp get <name>` shows one, `claude mcp remove <name>` deletes it, and typing `/mcp` inside a session shows its status, including whether it has connected yet. Two details worth knowing: Claude Code saves the configuration without checking credentials, so a wrong header fails only when it connects, and tool output is capped, with a default of 25,000 tokens and a warning from 10,000, which you can raise with `MAX_MCP_OUTPUT_TOKENS`. A result over the cap is not lost outright: the documentation says it is saved to a file and the conversation gets a reference to that file instead, so the agent has to go and read it. [The documentation](https://code.claude.com/docs/en/mcp) has the details.

It also carries a warning that applies to every server you add, ours included: only connect servers you trust, because one that fetches outside content can expose you to prompt injection. Read what a server's tools claim to do before you let an agent call them.

## What the free tools of a server should expose

Now the design question. If you run a server, the tools anyone can call without proof of anything are your public face. Ours are four, and each choice below comes from that set.

**Let an agent look before it decides.** Our `search_skills` takes a plain-language query, or a category, tag or language filter, and returns cards stating the purpose of a skill, its exclusions and the way it was tested. The query is limited to 100 characters and the answer to 24 cards. `list_categories` returns the twelve categories with a short introduction. Neither costs the caller anything, because browsing that requires a purchase is not browsing.

**Describe the paid thing completely, for free.** `get_skill` returns the card plus the exact payment-required body that the shop's HTTP endpoint answers with on a missing payment. An agent, or the person behind it, can see precisely what is being asked before any money moves. That matters because the decision to buy is a spending decision, and it should be made with the full facts in front of it.

**Put the paid action behind the protocol, not behind the tool.** The file itself is not returned by any of these tools. Buying is a plain HTTP request that answers with status 402, the client signs a payment, repeats the request with the signature in a header and receives the file. The MCP layer in our code has a comment saying it takes no payments, and the tool text says the same to the agent. Whether to pay stays a separate step, taken by the agent's own payment client under the owner's limits.

**Never put a key inside a tool.** None of our four tools holds a wallet key or spends money. The tool that works with an earlier purchase, `redownload_skill`, takes the buyer's own receipt token as input and returns the current version of a file that person already owns. A tool that can spend should not exist on a server you publish; if you need one, it belongs in software your user controls, with limits they set.

**Say in the description that it is free.** Each description of ours states whether the tool costs anything, because an agent weighing which tool to call reads mostly that text, plus the tool name and its input schema. A tool with a vague description gets skipped or misused.

**Keep answers small and structured.** Returning compact JSON cards respects the output cap above and keeps the agent's context for the job. A tool that dumps a whole catalogue ends up in a file the agent must open, which costs it extra steps and context.

## A quick check of a server you did not write

Before adding any MCP server to a machine that matters, list its tools and read each description as if it were instructions, because to the model it is. Ask three things. Does any tool spend money or write data? Does any tool return outside text that the agent will then act on? Is anything secret passed in by the caller? If you cannot answer, add the server only at local scope in a throwaway project first.

## When this does not apply

The commands here are for remote servers over HTTP; a server you run as a local process uses a different form of the command, which the same documentation describes. They also reflect one Claude Code version on one day, and options such as tool search or output limits are the kind of thing that moves. The design advice is one team's choices for a read-only catalogue that sells a file; a server that edits data, runs code or reaches private systems needs approvals, audit and scoped credentials that we have not built or measured. We did not test how often agents choose the right tool from our descriptions, nor how other clients treat the free tools.