<?xml version="1.0" encoding="utf-8" standalone="yes"?><rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:webfeeds="http://webfeeds.org/rss/1.0"><channel><title>mcp | Self-Hosted!</title><link>https://blog.brumarino.com/tags/mcp/</link><description>Post novo no “Rack” de segunda a sexta, às 7AM. Proxmox, rede, backup, UPS, IA e tudo o que tenho estudado.</description><language>pt-BR</language><managingEditor>Bruno Marino</managingEditor><image><url>https://blog.brumarino.com/brand/icon-144.png</url><title>mcp | Self-Hosted!</title><link>https://blog.brumarino.com/tags/mcp/</link><width>144</width><height>144</height></image><webfeeds:icon>https://blog.brumarino.com/brand/icon-192.png</webfeeds:icon><webfeeds:logo>https://blog.brumarino.com/brand/symbol.svg</webfeeds:logo><webfeeds:accentColor>2B3036</webfeeds:accentColor><lastBuildDate>Thu, 12 Nov 2026 07:00:00 -0300</lastBuildDate><atom:link href="https://blog.brumarino.com/tags/mcp/index.xml" rel="self" type="application/rss+xml"/><item><title>MCP no Claude Code: o que é e como ligar um servidor</title><link>https://blog.brumarino.com/mcp-claude-code/</link><pubDate>Thu, 12 Nov 2026 07:00:00 -0300</pubDate><guid>https://blog.brumarino.com/mcp-claude-code/</guid><category>IA no homelab</category><description>O que é MCP no Claude Code, como adicionar servidores stdio e http, escopos, segredos por variável, permissões mcp__ e o risco de injeção de prompt.</description><content:encoded><![CDATA[<p>Uma das coisas que estou estudando no Claude Code é o <strong>MCP</strong>. A sigla aparece em todo lugar, mas pouca explicação mostra o básico: o que é, como ligar um servidor e o que muda na segurança.</p>
<p>Este post é o resumo do que entendi lendo a documentação oficial, com o olhar de quem usa o Claude Code dentro dos containers do homelab. Se você ainda não conhece os comandos básicos, comece pelo post sobre <a href="/comandos-barra-claude-code/">os comandos com / do Claude Code</a>.</p>
<h2 id="o-que-é-mcp">O que é MCP <a class="anchor" href="#o-que-%c3%a9-mcp" aria-label="Link para esta seção">#</a></h2>
<p>MCP (Model Context Protocol) é um <strong>padrão aberto</strong> para ligar ferramentas de IA a outros sistemas. Um <strong>servidor MCP</strong> dá ao Claude Code acesso a ferramentas, bancos de dados e APIs que ele não tem por padrão.</p>
<p>A documentação dá uma regra prática boa: vale ligar um servidor quando você se pega <strong>copiando dados de outra ferramenta para colar no chat</strong>. Em vez de colar, o Claude lê e age direto no sistema.</p>
<p>Pensando em homelab, os exemplos são fáceis de imaginar: ler arquivos de uma pasta fora do projeto, consultar um banco, falar com a API de um serviço. Cada servidor MCP expõe algumas <strong>ferramentas</strong>, e o Claude decide quando usar cada uma, sempre passando pelas permissões que você definiu.</p>
<h2 id="os-três-tipos-de-conexão">Os três tipos de conexão <a class="anchor" href="#os-tr%c3%aas-tipos-de-conex%c3%a3o" aria-label="Link para esta seção">#</a></h2>
<p>O servidor MCP pode estar em dois lugares: rodando na sua máquina ou num serviço remoto. Isso define o transporte:</p>
<table>
	<thead>
			<tr>
					<th>Transporte</th>
					<th>Onde roda</th>
					<th>Quando usar</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>stdio</code></td>
					<td>Processo local, iniciado pelo Claude Code</td>
					<td>Ferramentas na própria máquina ou container</td>
			</tr>
			<tr>
					<td><code>http</code></td>
					<td>Servidor remoto</td>
					<td>É o recomendado para servidores remotos</td>
			</tr>
			<tr>
					<td><code>sse</code></td>
					<td>Servidor remoto</td>
					<td><strong>Obsoleto.</strong> Use <code>http</code> quando houver</td>
			</tr>
	</tbody>
</table>
<p>O comando é sempre o <code>claude mcp add</code>. Para um servidor remoto:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">claude mcp add --transport http meu-servico https://exemplo.com/mcp
</span></span></code></pre></div><p>Para um servidor local, o comando que inicia o servidor vem depois de um <code>--</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">claude mcp add --transport stdio arquivos <span class="se">\
</span></span></span><span class="line"><span class="cl">  -- npx -y @modelcontextprotocol/server-filesystem --read-only /srv/docs
</span></span></code></pre></div><p>O <code>--</code> separa as opções do Claude Code (<code>--transport</code>, <code>--env</code>, <code>--scope</code>) das opções do servidor. Tudo que vem depois dele vai para o servidor sem mexer. Sem o <code>--</code>, o Claude Code tentaria ler o <code>--read-only</code> como uma opção dele.</p>
<p>Esse exemplo usa o servidor de arquivos de referência do próprio projeto MCP. Ele só acessa as pastas passadas na linha de comando, e o <code>--read-only</code> faz o servidor nem oferecer as ferramentas de escrita. É um bom primeiro teste: o Claude passa a ler <code>/srv/docs</code>, mas não consegue alterar nada lá. Ele precisa do Node.js instalado, por causa do <code>npx</code>.</p>
<h2 id="onde-a-configuração-fica-escopos">Onde a configuração fica: escopos <a class="anchor" href="#onde-a-configura%c3%a7%c3%a3o-fica-escopos" aria-label="Link para esta seção">#</a></h2>
<p>Todo servidor tem um <strong>escopo</strong>, que define onde ele vale e onde fica salvo:</p>
<table>
	<thead>
			<tr>
					<th>Escopo</th>
					<th>Vale em</th>
					<th>Vai para o git?</th>
					<th>Fica em</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>local</code> (padrão)</td>
					<td>Só no projeto atual</td>
					<td>Não</td>
					<td><code>~/.claude.json</code></td>
			</tr>
			<tr>
					<td><code>project</code></td>
					<td>Só no projeto atual</td>
					<td>Sim</td>
					<td><code>.mcp.json</code> na raiz do projeto</td>
			</tr>
			<tr>
					<td><code>user</code></td>
					<td>Todos os seus projetos</td>
					<td>Não</td>
					<td><code>~/.claude.json</code></td>
			</tr>
	</tbody>
</table>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">claude mcp add --transport http meu-servico --scope project https://exemplo.com/mcp
</span></span></code></pre></div><p>O escopo <code>project</code> cria um <code>.mcp.json</code> que vai para o repositório. Por segurança, o Claude Code <strong>pede aprovação</strong> antes de usar um servidor vindo desse arquivo. Se você aprovou algo errado, o <code>claude mcp reset-project-choices</code> zera essas escolhas.</p>
<p>Para gerenciar o que já está configurado:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">claude mcp list            <span class="c1"># todos os servidores</span>
</span></span><span class="line"><span class="cl">claude mcp get arquivos    <span class="c1"># detalhes de um</span>
</span></span><span class="line"><span class="cl">claude mcp remove arquivos <span class="c1"># remove</span>
</span></span></code></pre></div><p>Dentro da sessão, o <code>/mcp</code> mostra o status de cada servidor e faz o login nos que pedem OAuth. O login abre no navegador, e os tokens são guardados e renovados sozinhos.</p>
<aside class="alert alert--tip">
  <p class="alert__title">Dica</p>
  <p>Antes de remover um servidor remoto com login, rode <code>claude mcp logout &lt;nome&gt;</code>. Pela documentação, o <code>remove</code> apaga o token local, mas não o revoga no serviço que o emitiu.</p>
</aside><h2 id="segredos-fora-do-repositório">Segredos fora do repositório <a class="anchor" href="#segredos-fora-do-reposit%c3%b3rio" aria-label="Link para esta seção">#</a></h2>
<p>A regra que mais repito no homelab vale aqui também: <strong>segredo não vai para o git</strong>. Contei as regras no post sobre <a href="/claude-code-regras-homelab/">as regras que dou ao Claude Code</a>.</p>
<p>O <code>.mcp.json</code> aceita variáveis de ambiente, justamente para isso:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json"><span class="line"><span class="cl"><span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="nt">&#34;mcpServers&#34;</span><span class="p">:</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="nt">&#34;minha-api&#34;</span><span class="p">:</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">      <span class="nt">&#34;type&#34;</span><span class="p">:</span> <span class="s2">&#34;http&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">      <span class="nt">&#34;url&#34;</span><span class="p">:</span> <span class="s2">&#34;${API_BASE_URL:-https://api.exemplo.com}/mcp&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">      <span class="nt">&#34;headers&#34;</span><span class="p">:</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">        <span class="nt">&#34;Authorization&#34;</span><span class="p">:</span> <span class="s2">&#34;Bearer ${API_KEY}&#34;</span>
</span></span><span class="line"><span class="cl">      <span class="p">}</span>
</span></span><span class="line"><span class="cl">    <span class="p">}</span>
</span></span><span class="line"><span class="cl">  <span class="p">}</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span>
</span></span></code></pre></div><p>O <code>${API_KEY}</code> é lido do ambiente na hora de carregar, e o <code>${VAR:-padrão}</code> usa um valor padrão se a variável não existir. O arquivo pode ir para o git sem a chave.</p>
<p>Dois detalhes da documentação:</p>
<ul>
<li>Se a variável não existir e não houver padrão, a configuração carrega mesmo assim, com o texto <code>${VAR}</code> literal, e o <code>claude mcp list</code> mostra um aviso.</li>
<li>Algumas variáveis de credencial do próprio Claude Code chegam <strong>vazias</strong> na URL e nos cabeçalhos de servidores remotos. Isso impede que um <code>.mcp.json</code> de terceiros vaze a sua chave para o servidor que ele aponta.</li>
</ul>
<h2 id="permissões-para-ferramentas-mcp">Permissões para ferramentas MCP <a class="anchor" href="#permiss%c3%b5es-para-ferramentas-mcp" aria-label="Link para esta seção">#</a></h2>
<p>As ferramentas de um servidor MCP passam pelo mesmo sistema de permissões do resto. O nome segue o formato <code>mcp__&lt;servidor&gt;__&lt;ferramenta&gt;</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json"><span class="line"><span class="cl"><span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="nt">&#34;permissions&#34;</span><span class="p">:</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="nt">&#34;allow&#34;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&#34;mcp__arquivos__*&#34;</span><span class="p">],</span>
</span></span><span class="line"><span class="cl">    <span class="nt">&#34;deny&#34;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&#34;mcp__outro-servidor__*&#34;</span><span class="p">]</span>
</span></span><span class="line"><span class="cl">  <span class="p">}</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span>
</span></span></code></pre></div><ul>
<li><code>mcp__arquivos__*</code> cobre todas as ferramentas do servidor <code>arquivos</code>.</li>
<li><code>mcp__arquivos__read_text_file</code> cobre só uma ferramenta.</li>
<li>Num <code>deny</code>, <code>mcp__*</code> bloqueia <strong>todas</strong> as ferramentas MCP de todos os servidores. Num <code>allow</code>, esse curinga sem servidor é ignorado: para liberar, é preciso nomear o servidor.</li>
</ul>
<p>Esse último ponto é um bom desenho. Não dá para liberar &ldquo;qualquer MCP&rdquo; sem querer.</p>
<h2 id="o-risco-que-importa-injeção-de-prompt">O risco que importa: injeção de prompt <a class="anchor" href="#o-risco-que-importa-inje%c3%a7%c3%a3o-de-prompt" aria-label="Link para esta seção">#</a></h2>
<p>A documentação é direta: <strong>confira se confia em cada servidor antes de ligar</strong>. Um servidor que busca conteúdo de fora (páginas, e-mails, issues) pode trazer texto escrito para enganar a IA. É a chamada injeção de prompt.</p>
<p>O que eu olharia antes de instalar um servidor MCP:</p>
<ol>
<li><strong>Quem mantém.</strong> Servidor oficial do serviço ou do projeto MCP é diferente de um pacote qualquer.</li>
<li><strong>O que ele consegue fazer.</strong> Se só precisa ler, procure um modo só leitura, como o <code>--read-only</code> do servidor de arquivos.</li>
<li><strong>O que ele lê de fora.</strong> Quanto mais conteúdo externo, mais cuidado com o que a IA pode ser levada a fazer.</li>
<li><strong>As permissões.</strong> Comece sem <code>allow</code> e deixe o Claude pedir. Libere ferramenta por ferramenta conforme confiar.</li>
</ol>
<aside class="alert alert--warning">
  <p class="alert__title">Atenção</p>
  <p>Servidor <code>stdio</code> roda como um processo com o mesmo usuário do Claude Code. Ele enxerga o que esse usuário enxerga. Dentro de um container dedicado o estrago possível é menor, e é por isso que o Claude Code fica nos containers e não no host Proxmox.</p>
</aside><p>Um detalhe prático: o Claude Code avisa quando a resposta de uma ferramenta MCP passa de 10 mil tokens e corta em 25 mil por padrão. Para aumentar o limite, existe a variável <code>MAX_MCP_OUTPUT_TOKENS</code>. Antes de subir, porém, vale perguntar se o servidor não está trazendo dados demais.</p>
<h2 id="resumindo">Resumindo <a class="anchor" href="#resumindo" aria-label="Link para esta seção">#</a></h2>
<ul>
<li><strong>MCP liga o Claude Code a outros sistemas.</strong> Use quando estiver copiando e colando dados de outra ferramenta.</li>
<li><strong><code>http</code> para remoto, <code>stdio</code> para local.</strong> O <code>sse</code> está obsoleto.</li>
<li><strong>O <code>--</code> separa</strong> as opções do Claude Code das opções do servidor.</li>
<li><strong>Escopo <code>local</code> é o padrão.</strong> O <code>project</code> vai para o git e pede aprovação.</li>
<li><strong>Segredo por variável</strong> (<code>${API_KEY}</code>), nunca escrito no <code>.mcp.json</code>.</li>
<li><strong>Permissões por servidor:</strong> <code>mcp__&lt;servidor&gt;__*</code>, e um <code>deny</code> com <code>mcp__*</code> bloqueia tudo.</li>
<li><strong>Confie antes de ligar.</strong> Servidor que lê conteúdo de fora traz risco de injeção de prompt.</li>
</ul>
<p>Meu próximo passo é escolher um servidor que resolva algo real no homelab, em vez de instalar por curiosidade. Quando tiver um caso de uso de verdade, ele vira post.</p>
]]></content:encoded></item></channel></rss>