Servidor MCP em Python: da consulta local ao HTTP autenticado

Um bom primeiro servidor resolve uma tarefa pequena: recebe o ID de um pedido e devolve o status. Comece por aí. Uma ferramenta genérica de acesso ao banco deixa decisões demais nas mãos do modelo e concede mais acesso do que esse fluxo precisa.

Este passo a passo segue o tutorial oficial de servidores vigente. Em 7 de outubro de 2026, a documentação usa a especificação MCP 2026-07-28 e o SDK oficial de Python, a biblioteca que processa as mensagens MCP, com sua API MCPServer. O exemplo fixa a versão SDK 2.3.0, para que os imports de um tutorial antigo não alterem silenciosamente o que você instala.

O que um servidor MCP disponibiliza?

Um servidor MCP funciona como um balcão de atendimento com regras de acesso entre uma aplicação de IA e seus sistemas. A aplicação pode consultar o que está disponível, fazer uma solicitação e receber uma resposta. Seu código define o que esse balcão pode fazer.

O MCP, Model Context Protocol, estabelece um formato comum para essa conversa. O host é a aplicação que você usa, como Claude Code ou Cursor. O cliente dela conduz a comunicação do protocolo com seu servidor. São papéis na arquitetura; você não precisa instalar três aplicações extras.

Uma ferramenta pode ser somente de leitura. Chamar algo de recurso não dispensa as verificações de acesso. Um prompt fornece instruções, não permissões. O suporte e a apresentação variam entre clientes, então verifique as funcionalidades que você de fato disponibiliza. Essas são as três primitivas de servidor; o servidor abaixo precisa apenas de uma ferramenta.

Antes de começar, veja se um conector com manutenção ativa já resolve a tarefa. Nossa seleção dos melhores servidores MCP de 2026 é um ponto de partida. Um servidor próprio se justifica quando seus dados internos, suas regras de permissão ou seu fluxo de trabalho diferem do que esses conectores oferecem.

Crie uma consulta de pedidos somente de leitura em Python

Use o SDK oficial para cuidar do protocolo e concentre seu código na consulta. Você precisa de Python 3.10 ou mais recente, uv, o gerenciador de projetos Python usado no tutorial oficial, e Node.js para o Inspector. A versão atual do Inspector exige Node 22.19.0 ou mais recente.

No terminal, execute estes comandos na sequência:

1. uv init orders-mcp
2. cd orders-mcp
3. uv venv
4. uv add "mcp[cli]==2.3.0"

Crie o arquivo orders.py nessa pasta e cole o servidor completo abaixo. Os registros são dados fictícios para aprendizado. Não há nomes de clientes, dados de pagamento ou credenciais de API.

import json

from mcp.server import MCPServer

mcp = MCPServer("orders")

# Fictional training data. No customer records or credentials.
ORDERS = {
    "A100": {"status": "shipped", "carrier": "Demo Courier"},
    "A101": {"status": "packing", "carrier": "not assigned"},
}


@mcp.tool()
def lookup_order(order_id: str) -> str:
    """Look up a fictional order by ID, such as A100. Read-only.

    Args:
        order_id: Exact order ID, for example A100 or A101.
    """
    key = order_id.strip().upper()
    order = ORDERS.get(key)
    if order is None:
        return json.dumps({"found": False, "order_id": key})
    return json.dumps({"found": True, "order_id": key, **order})


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

O código usa o padrão documentado no tutorial, com MCPServer, @mcp.tool() e mcp.run(transport="stdio"), substituindo as ferramentas de previsão do tempo por uma consulta de pedidos. A anotação de tipo string informa ao SDK que order_id é um campo de texto obrigatório. A docstring explica ao cliente quando a ferramenta é útil. O SDK gera a definição da ferramenta e processa as mensagens do protocolo.

Execute uv run orders.py. É normal que o processo fique silencioso, aguardando uma entrada. stdio, a entrada e a saída padrão, é o canal que o cliente usa para conversar com esse processo. Encerre essa execução manual antes de deixar um cliente iniciar sua própria cópia.

Não envie os logs da aplicação para a saída padrão. Use o módulo logging do Python, que escreve em stderr por padrão. Um print() fora de lugar pode corromper o fluxo do protocolo. Essa é uma restrição documentada do stdio, e não apenas uma preferência de organização dos logs.

Ao trocar o dicionário por um banco de dados, mantenha a mesma interface enxuta. Faça uma consulta parametrizada, use uma conta de banco que só possa ler os campos necessários e verifique as permissões de quem fez a chamada antes de retornar um registro. Para essa tarefa, nunca aceite uma instrução SQL arbitrária do modelo.

Valide a ferramenta com o MCP Inspector

Confirme que a ferramenta funciona antes de pedir a um modelo para usá-la. Na pasta do projeto, execute uv run mcp dev orders.py. O comando de desenvolvimento do SDK inicia o MCP Inspector. Abra no navegador a URL exibida pelo comando e conecte o servidor, caso a conexão ainda não esteja ativa.

Em Tools, selecione lookup_order. O formulário deve mostrar o campo obrigatório order_id. Faça uma chamada com A100: o resultado deve conter found: true, status: shipped e carrier: Demo Courier. Consulte A101 para obter packing. Consulte DOES-NOT-EXIST: o resultado deve conter found: false.

Teste também uma solicitação sem order_id. Ela deve falhar na validação da entrada, sem executar a consulta. As visualizações Protocol e Console do Inspector ajudam a distinguir uma solicitação malformada de uma falha no processo do servidor.

Para repetir a verificação pelo terminal, use npx @modelcontextprotocol/inspector --cli uv run orders.py --method tools/list. Para chamar a ferramenta, use npx @modelcontextprotocol/inspector --cli uv run orders.py --method tools/call --tool-name lookup_order --tool-arg order_id=A100. Esses comandos seguem a CLI documentada do Inspector.

O critério de sucesso é concreto: uma ferramenta que o cliente consegue descobrir, o status esperado para um pedido conhecido e uma resposta explícita quando o registro não existe. Um parágrafo convincente gerado pelo modelo não comprova que a consulta foi executada.

Conecte o mesmo servidor ao Claude Code e ao Cursor

Cada cliente local inicia seu próprio processo de servidor. Não é preciso manter o Inspector aberto. Use caminhos absolutos para que a inicialização não dependa da pasta que o cliente abrir.

Claude Code: execute claude mcp add --transport stdio --scope local orders -- /ABSOLUTE/PATH/orders-mcp/.venv/bin/python /ABSOLUTE/PATH/orders-mcp/orders.py. No Windows, o interpretador fica em .venv\Scripts\python.exe. O comando segue a sintaxe de servidor local do Claude Code, incluindo o separador -- antes do comando de inicialização.

Execute claude mcp get orders para verificar a conexão. Em uma sessão do Claude Code, abra /mcp e peça: “Use lookup_order para consultar A100. Informe apenas o status e a transportadora retornados.” Confira a chamada da ferramenta e seus argumentos.

Cursor: crie .cursor/mcp.json no projeto. Adicione este JSON, substituindo os dois caminhos absolutos: {"mcpServers":{"orders":{"type":"stdio","command":"/ABSOLUTE/PATH/orders-mcp/.venv/bin/python","args":["/ABSOLUTE/PATH/orders-mcp/orders.py"]}}}.

Abra Customize, habilite o servidor e faça a mesma pergunta no Agent. Revise a chamada conforme suas configurações de aprovação. O local do arquivo, os campos de inicialização e os controles seguem a configuração MCP do Cursor. Se a conexão falhar, verifique o caminho do executável e a saída de erro padrão do servidor antes de alterar a ferramenta.

Quando usar stdio local ou HTTP remoto?

Para um fluxo pessoal, mantenha o servidor local. Escolha HTTP remoto quando várias pessoas ou clientes hospedados precisarem de um serviço gerenciado em comum.

Um serviço remoto também precisa de acesso de rede aos dados da empresa. Publicar um endpoint não torna um banco privado acessível nem garante que suas permissões estejam corretas.

O protocolo HTTP 2026-07-28 usa solicitações autocontidas. O SDK Python atual também pode atender clientes antigos, cujas sessões podem exigir roteamento persistente para a mesma instância quando você adicionar réplicas. Configure os ajustes de compatibilidade documentados de forma deliberada antes de escalar; não presuma que todos os clientes conectados usem a revisão mais recente.

Leve a consulta para HTTP com autenticação

Proteja o acesso HTTP com tokens emitidos para esse serviço. OAuth 2.1 é o framework de autorização da especificação MCP: um provedor de identidade autentica o usuário e emite um token, enquanto seu servidor MCP verifica esse token. Um escopo é uma permissão nomeada, como orders:read. A audiência define qual serviço pode aceitar o token.

O SDK fornece a integração do servidor de recursos, não o sistema de login da empresa. Para este exemplo, configure um provedor de identidade com descoberta OAuth, registro de clientes para os aplicativos escolhidos, PKCE no login do usuário — que comprova que o aplicativo concluindo o login é o mesmo que o iniciou — e um endpoint de introspecção de tokens. A introspecção consulta o emissor para saber se um token está ativo e o que ele permite.

Este adaptador espera uma introspecção por HTTPS com autenticação de cliente via HTTP Basic e uma resposta que contenha active, aud, exp, client_id e scope. Configure o emissor para incluir a URL pública exata desse endpoint em aud e conceder orders:read. Se seu provedor usar outro método de autenticação na introspecção, adapte a solicitação conforme a documentação dele. Se fornecer JWTs, tokens assinados, implemente a verificação de assinatura, emissor, validade e audiência na mesma interface TokenVerifier.

Adicione uvicorn com uv add uvicorn e crie remote.py ao lado de orders.py. O código segue o exemplo oficial de introspecção do SDK e suas interfaces documentadas de HTTP e autenticação. Ele reaproveita a consulta que você acabou de testar.

import os
import time
from urllib.parse import urlsplit

import httpx2
from pydantic import AnyHttpUrl

from mcp.server import MCPServer
from mcp.server.auth.provider import AccessToken, TokenVerifier
from mcp.server.auth.settings import AuthSettings
from mcp.server.transport_security import TransportSecuritySettings
from orders import lookup_order as local_lookup

RESOURCE = os.environ["MCP_RESOURCE_URL"]
ISSUER = os.environ["MCP_ISSUER_URL"]
INTROSPECT = os.environ["MCP_INTROSPECTION_URL"]
if any(urlsplit(url).scheme != "https" for url in (RESOURCE, ISSUER, INTROSPECT)):
    raise ValueError("Public auth and resource URLs must use HTTPS")


class OrderTokenVerifier(TokenVerifier):
    async def verify_token(self, token: str) -> AccessToken | None:
        try:
            async with httpx2.AsyncClient(timeout=5.0) as client:
                response = await client.post(
                    INTROSPECT,
                    data={"token": token},
                    auth=(os.environ["MCP_INTROSPECTION_CLIENT_ID"],
                          os.environ["MCP_INTROSPECTION_CLIENT_SECRET"]),
                )
                response.raise_for_status()
                data = response.json()
            audiences = data.get("aud", [])
            if isinstance(audiences, str):
                audiences = [audiences]
            expiry = data.get("exp")
            if (data.get("active") is not True or RESOURCE not in audiences
                    or not isinstance(expiry, int) or expiry <= time.time()):
                return None
            if data.get("iss", ISSUER) != ISSUER:
                return None
            return AccessToken(
                token=token, client_id=data["client_id"],
                scopes=data.get("scope", "").split(), expires_at=expiry,
                resource=RESOURCE, subject=data.get("sub"),
            )
        except Exception:
            return None


mcp = MCPServer(
    "orders",
    token_verifier=OrderTokenVerifier(),
    auth=AuthSettings(
        issuer_url=AnyHttpUrl(ISSUER),
        resource_server_url=AnyHttpUrl(RESOURCE),
        required_scopes=["orders:read"], validate_token_resource=True,
    ),
)


@mcp.tool()
def lookup_order(order_id: str) -> str:
    """Look up a fictional order by ID, such as A100. Read-only."""
    return local_lookup(order_id)


hostname = urlsplit(RESOURCE).hostname
security = TransportSecuritySettings(
    allowed_hosts=[hostname, f"{hostname}:*"],
    allowed_origins=[os.environ["MCP_ALLOWED_ORIGIN"]],
)
app = mcp.streamable_http_app(transport_security=security)

Defina estes valores no ambiente de implantação ou no gerenciador de segredos:

A lista de hosts permitidos é explícita porque, por padrão, o SDK aceita localhost e rejeita um hostname público com 421 Misdirected Request. A verificação das origens do navegador é independente; liste apenas as que você realmente usa. A aplicação retornada já inclui seu ciclo de inicialização e encerramento. Esses detalhes seguem a documentação de implantação do SDK e de aplicações ASGI. ASGI é a interface que os servidores web Python usam para executar essa aplicação.

Inicie o serviço atrás do proxy HTTPS da hospedagem com uv run uvicorn remote:app --host 0.0.0.0 --port 8000. A URL pública do recurso continua sendo HTTPS mesmo que o proxy se comunique com o processo por HTTP. Configure a confiança nos cabeçalhos encaminhados de acordo com o limite real do proxy dessa hospedagem.

Antes de usar registros reais, faça estas verificações pelo HTTP:

• Sem token, com token expirado ou com token destinado a outra audiência: o acesso é recusado.
• Token válido sem orders:read: o acesso é recusado.
• Token válido com a audiência e o escopo corretos: lookup_order retorna o status de demonstração.
• /.well-known/oauth-protected-resource/mcp: os metadados identificam o recurso e o emissor corretos.

Use npx @modelcontextprotocol/inspector --server-url https://orders.example.com/mcp --transport http para inspecionar o endpoint publicado e concluir seu fluxo de autenticação. Um teste da ferramenta em memória não passa pela autorização HTTP, portanto não comprova que essa barreira funciona.

No Claude Code, adicione uma conexão separada com claude mcp add --transport http orders-remote https://orders.example.com/mcp e autentique-se pelo /mcp. No Cursor, adicione uma entrada remota em mcpServers com "url":"https://orders.example.com/mcp" e conclua o OAuth. O Cursor também documenta um objeto auth com CLIENT_ID e scopes para clientes previamente registrados. Registre no emissor os callbacks apropriados de cada cliente. Consulte a autenticação do Claude Code e a configuração de OAuth remoto do Cursor.

Este é um adaptador autenticado enxuto, não um sistema de produção completo. Antes de substituir o dicionário de demonstração, aplique as permissões por tenant e por registro com base na identidade verificada, registre um evento de auditoria da chamada, reutilize conexões HTTP e limite as solicitações. Um escopo permite a operação; ele não comprova que o usuário tem direito de acesso a todos os pedidos.

Hospede no Render ou no Cloudflare Workers

Para o servidor Python acima, eu começaria pelo Render. Um serviço web Python mantém a aplicação que você já construiu. O Cloudflare Workers é uma boa opção se você quiser implementar a mesma ferramenta de escopo restrito no handler documentado para Workers.

Estes são os preços publicados pelos fornecedores, verificados em 7 de outubro de 2026:

Fontes: preços do Cloudflare Workers e preços do Render. O workspace Pro do Render acrescenta $25/mês mais a instância de computação, caso você escolha seus recursos para equipes. Armazenamento, serviços de identidade, uso de modelos e outros extras precisam de orçamento separado; esses são preços de hospedagem, não o custo de um fluxo de trabalho com IA.

Deploy no Render: coloque orders.py, remote.py e requirements.txt no repositório. O arquivo de dependências precisa de mcp[cli]==2.3.0 e uvicorn, cada um em sua própria linha. Crie um Python Web Service, use o comando de build pip install -r requirements.txt e o comando de inicialização uvicorn remote:app --host 0.0.0.0 --port $PORT. Adicione as variáveis de ambiente descritas acima e informe o hostname atribuído ou seu domínio próprio em MCP_RESOURCE_URL. Isso adapta a implantação documentada de serviços web Python no Render à aplicação ASGI do SDK.

O serviço gratuito do Render serve para uma demonstração, mas entra em suspensão após 15 minutos sem atividade e leva cerca de um minuto para reativar. Para uma ferramenta interativa compartilhada, eu usaria uma instância paga.

Deploy no Cloudflare: siga a documentação atual do handler MCP e o guia de servidor remoto. A implementação atual em TypeScript usa createMcpHandler de agents/mcp/server com @modelcontextprotocol/server. Implemente ali a mesma consulta de pedidos e configure a autenticação antes de compartilhar a URL. O comando de inicialização Python com uvicorn é destinado a uma hospedagem Python; ele não é uma receita de deploy em Worker.

Restrinja o acesso ao que a ferramenta precisa

Dê ao servidor apenas o acesso exigido pela ferramenta. Para consultar o status de um pedido, isso significa uma credencial de backend somente de leitura, campos selecionados e uma verificação de permissão por registro. Mantenha reembolsos, cancelamentos e alterações de endereço em ferramentas e permissões separadas. Os argumentos escolhidos pelo modelo nunca substituem a autorização.

Valide nos tokens HTTP o emissor, a validade, a audiência e o escopo. Use HTTPS e credenciais separadas quando o servidor chamar uma API de outro sistema. As orientações de segurança do MCP proíbem o repasse de tokens: um token apresentado ao seu endpoint MCP não é automaticamente uma credencial para o sistema de pedidos. No stdio local, restrinja o processo que inicia o servidor, seu ambiente e seu acesso ao sistema de arquivos.

Registre a identidade verificada de quem fez a chamada, o nome da ferramenta, uma referência ao registro com os dados sensíveis devidamente ocultados, o resultado, a latência e o ID da solicitação. Evite tokens e registros completos de clientes. No stdio, mantenha os logs na saída de erro padrão; no HTTP, use o sistema de logs da hospedagem. Trate o texto obtido dos registros como dado; uma observação dentro de um pedido não pode conceder permissão para outra ação.

Coloque um gateway na frente quando vários servidores ou equipes precisarem compartilhar políticas de identidade, limites de requisições, coleta de auditoria ou revogação. O gateway pode centralizar esses controles; cada backend continua precisando de permissões corretas por registro. Nosso guia de gateways MCP explica essa decisão.

Seis usos práticos, em ordem de retorno imediato

Estas são possíveis extensões do mesmo padrão. Comece por uma tarefa em que alguém consulta repetidamente uma informação específica e sabe reconhecer a resposta correta.

O cálculo do retorno deve partir do seu próprio fluxo de trabalho. Exemplo meramente ilustrativo: 80 consultas por dia, com 2 minutos cada, consomem 160 minutos. Se a medição posterior mostrar que o fluxo conectado economiza 1 minuto por consulta, são 80 minutos recuperados por dia. Isso é aritmética, não um benchmark de desempenho. Meça a precisão das respostas e o tempo economizado antes de atribuir retorno ao gasto com hospedagem.

Duas oportunidades de produto

A oportunidade mais forte é um adaptador de contexto de pedidos para equipes de suporte. Uma equipe poderia comprar uma integração focada em buscar os dados corretos da entrega dentro do assistente que já usa. O DataForSEO estima 260 buscas mensais no Google dos EUA por “customer support automation”, dado verificado em 7 de outubro de 2026. Isso indica interesse amplo nessa tarefa, não um número de compradores de MCP. O Intercom anuncia o Fin a $0.99 por resultado, o que mostra que já existe orçamento para automação de suporte; esse pequeno adaptador fornece contexto, em vez de substituir o produto.

A menor versão comercializável poderia atender um único backend de pedidos, incluir lookup_order, login com escopo definido, uma trilha de auditoria e um rascunho de resposta que cite os campos retornados. A vantagem estaria em se ajustar aos dados e às regras de acesso de uma empresa específica. O desafio é que os fornecedores atuais talvez já ofereçam o conector, e as licenças de acesso aos modelos, a limpeza dos dados e o suporte da equipe também custam dinheiro. Valide essa lacuna com um responsável pelo suporte antes de acrescentar ferramentas.

Uma consulta de políticas internas que respeite as permissões é a segunda oportunidade. Um profissional poderia dar acesso ao acervo de políticas aprovadas de uma empresa por meio de recursos ou de uma ferramenta de busca com escopo restrito. O DataForSEO estima 390 buscas mensais nos EUA por “enterprise search”, dado verificado na mesma data. O MVP poderia incluir um acervo, citações das fontes, verificações de atualização e filtragem pelas permissões da pessoa autenticada. O desafio é que a qualidade da recuperação e o controle de acesso são o produto; expor uma pasta via MCP é fácil de copiar. O volume de buscas sinaliza demanda pela tarefa mais ampla, sem provar que os usuários pagarão por essa implementação.

Quais problemas o MCP não resolve?

O MCP padroniza o acesso. A qualidade dos dados, a autorização, a confiabilidade do backend e a definição do que uma ferramenta pode fazer continuam sob sua responsabilidade. Um modelo pode interpretar mal um resultado válido, e clientes conectados podem oferecer suporte diferente às funcionalidades ou ter políticas de aprovação distintas.

Construa esse servidor quando uma interface compartilhada de ferramentas melhorar um fluxo que você consiga medir. Para um processamento em lote fixo que nunca precise de um assistente para escolher uma ferramenta, uma chamada de API comum ou um script pode ser a melhor implementação.

Para colocar em prática na segunda-feira: escolha uma consulta recorrente com alguém do suporte, use registros fictícios para conectar os dois clientes e, depois, substitua os dados usando uma conta somente de leitura e teste as permissões por registro. Deixe as operações de escrita fora dessa primeira implantação. Passe para HTTP compartilhado quando o fluxo e os controles de identidade estiverem prontos.

Se você quer um serviço MCP conectado aos dados da empresa, desenvolvido e operado para sua equipe, nosso serviço de sistemas de IA em produção cobre a integração e seus controles de acesso.