Conecte-se a um host de verdade

Um host é a aplicação dentro da qual seu servidor acaba rodando: Claude Desktop, Claude Code, uma IDE. O host é aquilo com que o usuário conversa. Dentro dele, um cliente MCP inicia seu servidor como um processo filho e fala com ele pelo stdin e stdout desse processo.

Ou seja, conectar a um host é um ato só: você informa a ele o comando que inicia seu servidor. Tudo nesta página (dois comandos de CLI, três arquivos JSON) é um lugar diferente para colocar esse mesmo comando.

Um servidor, todos os hosts

from mcp.server import MCPServer

mcp = MCPServer("Bookshop")

CATALOG = {
    "Dune": "Frank Herbert",
    "Neuromancer": "William Gibson",
    "The Left Hand of Darkness": "Ursula K. Le Guin",
}


@mcp.tool()
def search_books(query: str) -> list[str]:
    """Search the catalog by title or author."""
    needle = query.lower()
    return [title for title, author in CATALOG.items() if needle in title.lower() or needle in author.lower()]


@mcp.tool()
def get_author(title: str) -> str:
    """Look up the author of a book in the catalog."""
    if title not in CATALOG:
        raise ValueError(f"No book titled {title!r} in the catalog.")
    return CATALOG[title]


@mcp.resource("catalog://titles")
def titles() -> str:
    """Every title in the catalog, one per line."""
    return "\n".join(sorted(CATALOG))


if __name__ == "__main__":
    mcp.run()

Duas ferramentas (tools) e um recurso, um arquivo só. Três coisas sobre esse arquivo importam para todos os hosts abaixo:

• mcp.run() sem argumentos inicia um servidor stdio: ele bloqueia, lê mensagens do protocolo no stdin e as escreve no stdout. Esse é o transporte que todos os hosts desta página falam. O host inicia seu arquivo como um processo filho e é dono desses dois pipes, e é por isso que conectar nunca passa de "aqui está o comando". Você nunca escolhe uma porta, e nada fica escutando em uma.
• run() fica dentro de if __name__ == "__main__":. Tudo abaixo importa este arquivo em vez de executá-lo, então um run() sem essa proteção iniciaria um servidor no instante em que qualquer coisa carregasse o módulo.
• O objeto do servidor é uma global de nível de módulo chamada mcp. É esse o nome que mcp run procura (server e app também funcionam). Dê outro nome a ele e você precisa informá-lo explicitamente: mcp run server.py:bookshop.

Essa é a última linha de Python nesta página. Daqui para baixo é tudo configuração de host.

O comando de inicialização

Todos os hosts abaixo recebem o mesmo comando:

uv run --with "mcp[cli]" mcp run /absolute/path/to/server.py

Um comando só para todos eles porque uv run --with resolve o SDK em um ambiente novo na hora: funciona a partir de qualquer diretório e não precisa de projeto nem de ambiente virtual para ativar. Isso importa aqui mais do que em qualquer outro lugar, porque um host inicia seu servidor a partir do diretório de trabalho dele, com um ambiente quase vazio, e não a partir do seu shell.

É também o comando que mcp install grava na configuração do Claude Desktop para você (abaixo), então o que você digita à mão e o que o utilitário gera coincidem, fora o pin exato de versão que o utilitário adiciona.

Claude Desktop

O único host que o SDK consegue configurar para você:

uv run mcp install server.py

É só isso. mcp install importa o arquivo para ler o nome do servidor, encontra o arquivo de configuração do Claude Desktop e grava o comando de inicialização nele. De passagem, já converte o caminho para absoluto, então você não precisa fazer isso.

Não há mistério nenhum. Esta é a entrada que ele grava:

{
  "mcpServers": {
    "Bookshop": {
      "command": "/absolute/path/to/uv",
      "args": [
        "run",
        "--frozen",
        "--with",
        "mcp[cli]==2.0.0",
        "mcp",
        "run",
        "/absolute/path/to/server.py"
      ]
    }
  }
}

É o comando de inicialização da seção acima com três acréscimos: o caminho absoluto do uv, --frozen para que o uv nunca reescreva um lockfile que por acaso esteja por perto, e um pin exato na versão do mcp que você tem instalada. Ele vai parar em claude_desktop_config.json, que fica em:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Você pode escrever esse arquivo à mão. mcp install existe para você não cometer o erro clássico (um caminho relativo) ao fazer isso.

Encerre o Claude Desktop por completo (não só a janela) e abra-o de novo.

Claude Code

Não há arquivo para editar. Registre o servidor com a CLI claude; tudo depois de -- é o comando de inicialização.

claude mcp add bookshop -- uv run --with "mcp[cli]" mcp run /absolute/path/to/server.py

Execute /mcp dentro de uma sessão do Claude Code para confirmar que bookshop está conectado e que suas ferramentas aparecem listadas.

Cursor

Crie .cursor/mcp.json na raiz do seu projeto.

{
  "mcpServers": {
    "bookshop": {
      "command": "uv",
      "args": ["run", "--with", "mcp[cli]", "mcp", "run", "/absolute/path/to/server.py"]
    }
  }
}

Os mesmos command e args, sob a mesma chave mcpServers que o Claude Desktop usa. O servidor aparece nas configurações de MCP do Cursor com as duas ferramentas listadas.

VS Code

Crie .vscode/mcp.json na raiz do seu projeto.

{
  "servers": {
    "bookshop": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--with", "mcp[cli]", "mcp", "run", "/absolute/path/to/server.py"]
    }
  }
}

Duas diferenças em relação ao arquivo do Cursor, e são as únicas duas: a chave externa é servers, não mcpServers, e cada entrada declara seu type. Confirme o diálogo de confiança e, em seguida, MCP: List Servers na paleta de comandos mostra bookshop rodando.

Não aparece

Antes de mexer em qualquer configuração de host, execute você mesmo o comando de inicialização:

uv run --with "mcp[cli]" mcp run /absolute/path/to/server.py

Nada é impresso, e ele não retorna. Esse silêncio está certo: um servidor stdio está esperando um host falar primeiro no stdin (Ctrl-C para pará-lo). Um traceback ou uma saída imediata é o bug de verdade, e agora você consegue lê-lo em vez de tentar adivinhá-lo através de um host.

Uma vez que esse comando fica parado esperando, o que sobra é quase sempre uma de três coisas:

• Um caminho relativo. O host inicia seu servidor a partir do diretório de trabalho dele, não daquele de onde você fez o registro. server.py onde é preciso /absolute/path/to/server.py é, de longe, a falha mais comum. Se o host também não encontrar o uv, esse caminho precisa ser absoluto também.
• O host ainda está rodando a configuração antiga. Os hosts leem a configuração ao iniciar. O Claude Desktop, em particular, precisa ser encerrado por completo (não basta fechar a janela) e reaberto para que uma edição em claude_desktop_config.json tenha efeito.
• Algo chegou ao stdout fora do intervalo de desvio. No stdio, o stdout é o protocolo. O SDK desvia para o stderr a saída avulsa descarregada (com flush) enquanto está servindo, mas uma saída descarregada no stdout antes disso (um script wrapper que ecoa algo, um print() em tempo de importação em um processo sem buffer), ou um print() em buffer que só é descarregado quando o interpretador encerra, entrega ao host uma mensagem corrompida, e ele derruba a conexão. Registre os logs usando a configuração padrão do logging, cujo handler de stderr faz flush de cada registro; handlers personalizados também precisam evitar o stdout. Logging tem a história completa.

O Claude Desktop mantém um log por servidor: mcp-server-<NAME>.log é o stderr do seu servidor, ao lado de mcp.log para as conexões, em ~/Library/Logs/Claude no macOS e %APPDATA%\Claude\logs no Windows.

Para qualquer coisa além dessas três, a página é Solução de problemas.

Recapitulando

• Um host (Claude Desktop, uma IDE) executa um cliente MCP que inicia seu servidor como processo filho via stdio. Conectar significa dar a ele um comando de inicialização.
• Esse comando é uv run --with "mcp[cli]" mcp run /absolute/path/to/server.py: nenhum venv para ativar, funciona a partir de qualquer diretório.
• Claude Desktop é o único host que mcp install configura para você. Ele grava esse mesmo comando (mais o caminho absoluto do uv, --frozen e um pin exato na versão que você tem instalada) em claude_desktop_config.json, para você nunca precisar fazer isso.
• Claude Code é claude mcp add bookshop -- <launch command>. Cursor é .cursor/mcp.json sob mcpServers. VS Code é .vscode/mcp.json sob servers, cada entrada com um type.
• Caminhos absolutos em todo lugar, reinicie o host depois de editar a configuração dele, e nunca deixe nada além do SDK escrever no stdout.

Todos os hosts desta página se conectaram ao mesmo arquivo, com o mesmo comando. O que esse arquivo pode expor é o resto desta documentação: Ferramentas, Recursos e todos os transportes além do stdio em Executando seu servidor.