# Install an AnyMCP server

> AnyMCP is a catalog of MCP servers. Each server is one C# file. Save the file, then point your
> MCP client to `dotnet run <file>.cs -v q`. There is no project file, no build step of your own,
> and no container. The .NET 10 SDK is the only requirement.

This page gives the steps that are the same for each server and for each MCP client. The last step,
the client configuration, is different for each client. This page sends you to the page of your
client. Each server also has its own page with the exact values for that server. Start at that page:

- Catalog index for agents: https://anymcp.net/llms.txt
- Catalog as JSON: https://anymcp.net/servers.json
- One server: https://anymcp.net/servers/<id>/index.md

**Install the server into the project. This is the default.** Put the server file in the project.
Put the configuration in the configuration file of the project. These steps write no file outside the
project directory, and they change no other project on the computer. Install the server for the user
only if the user asks for it.

**Do all the commands on this page in the root directory of the project.** Each path is relative to
that directory. Do not change the working directory between the steps. If you go into
`.mcp-servers/` to read the file, go back to the root directory before the next command. If you do
not go back, the relative path becomes double and the command fails.

## Before you start: the .NET 10 SDK

```
dotnet --list-sdks
```

One line of the output must show version 10 or a later version. A file-based app with `#:package`
directives is a feature of the .NET 10 SDK. Each SDK before version 10 fails, and the error message
does not always give the cause. An SDK after version 10, for example version 11, is correct.

Use `--list-sdks`. Do not use `--version`. The `dotnet --version` command gives the SDK that the
computer selects now. A `global.json` file can select an earlier SDK on a computer that also has
version 10 or a later version.

If the computer has no `dotnet` command, or if all the versions are lower than 10, install the SDK
first:

- Windows: `winget install Microsoft.DotNet.SDK.10`
- macOS: `brew install --cask dotnet-sdk`, or the installer from https://dotnet.microsoft.com/download
- Linux: obey https://learn.microsoft.com/dotnet/core/install/linux for your distribution

Open a new shell after the installation. Then the shell finds `dotnet` on the PATH.

## Step 1. Put the file in the project

Do these commands in the root directory of the project:

```
mkdir -p .mcp-servers
curl -fsSL -o .mcp-servers/<file>.cs https://anymcp.net/servers/<id>/<id>.cs
```

PowerShell has a different `curl` command. In PowerShell, use `Invoke-WebRequest`:

```
New-Item -ItemType Directory -Force .mcp-servers | Out-Null
Invoke-WebRequest -Uri "https://anymcp.net/servers/<id>/<id>.cs" -OutFile ".mcp-servers/<file>.cs"
```

Commit the file. The file is the full server. A person who clones the project needs no other file.

Each client starts the same file. The server file is shared, and the configuration file is not.

## Step 2. Build one time, before you register the server

Do this command in the root directory of the project:

```
dotnet build .mcp-servers/<file>.cs -v q
```

Keep `-v` and `q` as separate arguments.

**A correct build prints no text.** The `-v q` option removes the summary, and there is no
`Build succeeded` line. Empty output and exit code 0 are the correct result. Do not do the command
again. A build that fails prints the errors.

The first build gets the NuGet packages and compiles the file. If the package cache is empty, this
takes from 30 seconds to two minutes. Most MCP clients give a stdio server approximately 30 seconds
to answer `initialize`. If you do not build the server first, the client reports a connection
failure that is only a timeout. Build the server one time manually, and the first client start is
quick.

**The build adds no file to the project.** A file-based app is not a project, and the SDK makes no
`bin` directory and no `obj` directory near the `.cs` file. The SDK keeps the compiled output in a
cache of the user: `%TEMP%/dotnet/runfile/` on Windows, and `$TMPDIR/dotnet/runfile/` on the other
operating systems. The name of the cache directory contains the name of the file and a hash of the
content of the file. Because of this, `.gitignore` needs no new line, and a `git status` command
after a build shows only the `.cs` file that you added.

## Step 3. MCP client setup

The catalog supports Claude Code and Codex. They read different configuration files, and the two
formats are not the same. **Do not copy the configuration format of one client into the file of the
other client.**

| Client | Configuration file | Read this page |
|---|---|---|
| Claude Code, Claude Desktop, Cursor, Windsurf | `.mcp.json` in the project root | https://anymcp.net/install/claude-code.md |
| Codex | `.codex/config.toml` in the project root | https://anymcp.net/install/codex.md |

Visual Studio and VS Code also read a JSON file, with the key `servers` in place of `mcpServers`.
Read the Claude Code page for that shape.

**Ask the user which client they use, before you write a configuration file.** Do not guess. A file
for the wrong client gives a client with no server, and no error message.

Both files belong to the project, and both go into version control. The `.mcp-servers/<file>.cs`
file is shared, and both clients start it with the same command.

Each client page also gives the end state that an agent can reach. An agent cannot start the client
again, so each page names the last steps that only a person can do.

## Why the `-v q` option is necessary

Stdio transport uses standard output for the JSON-RPC messages. Without `-v q`, the `dotnet run`
command can write build output to standard output. One such line breaks the protocol stream. The
client then reports a parse error, or shows no tool.

Keep `-v q` in each configuration. It is two elements, `"-v"` and `"q"`. It is not one element
`"-v q"`.

## Do not test the server manually

If you send JSON-RPC lines in one block, the server gives no output. Standard input comes to the end
of the file before the host answers `initialize`, and the log shows only
`transport completed reading messages`. This looks like a defective server, but the server is
correct. The first client start is the test.

## Tool names

The C# SDK changes each method name to snake case. The method `GeneratePassword` is
`generate_password` on the wire. The page of each server gives the two names.

## Secrets

The page of a server gives the name of each key that the server needs. Each AnyMCP server starts and
lists its tools when no key is set. The server needs a key only when the model calls a tool. A
failure at the start is thus never a missing key.

A configuration file is a part of the project and goes into version control. Write the name of a
variable in that file. Never write a value in it. The two clients name a variable in different ways,
and each client page gives the shape.

## Remove a server

Delete the entry of the server from the configuration file of your client, and then delete the
`.mcp-servers/<file>.cs` file. Each client page gives the exact command.

## Problems and their causes

| Problem | Cause |
|---|---|
| A command fails on a path that contains `.mcp-servers` two times | The shell is in the `.mcp-servers/` directory. Go back to the root directory of the project. |
| `dotnet build` prints no text | This is correct. The `-v q` option removes the summary. Look at the exit code. |
| The connection times out at the first start | You did not build the server. Do step 2, then register the server again. |
| The client connects, but shows no tool | The SDK is earlier than version 10, or the path in the arguments is wrong. |
| The client log shows a JSON parse error | The argument list has no `-v` and `q`, and build output came to standard output. |
| `dotnet: command not found` | The .NET 10 SDK is not installed, or it is not on the PATH. |
| The server operates for you, but not for a different user | That user did not do step 2. The build cache is for one user only. |
| The client shows no server, and gives no error | You wrote the file of the other client. Read the page of your client in step 3. |