Team Relay MCP

EVC Team Relay - Servidor MCP

Dê ao seu agente de IA acesso de leitura/escrita ao seu cofre Obsidian.

Seu agente lê suas notas, cria novas e permanece sincronizado — tudo através da API Team Relay.

Funciona com Claude Code, Codex CLI, OpenCode e qualquer cliente compatível com MCP.

Início Rápido

1. Instalação

Opção A — via PyPI (recomendado):

Nenhuma instalação necessária — uvx baixa e executa automaticamente. Pule para a etapa 2.

Opção B — a partir do código-fonte:

git clone https://github.com/entire-vc/evc-team-relay-mcp.git
cd evc-team-relay-mcp
uv sync   # or: pip install .

2. Configure sua ferramenta de IA

Adicione o servidor MCP à configuração da sua ferramenta. Escolha um método de autenticação:

Chave de agente (recomendado) — crie uma chave nas configurações do plugin Obsidian → Team Relay → Chaves de Agente. Suporta leitura e escrita: list_files, read_file, tr_search e upsert_file funcionam com uma única chave. Início rápido →

E-mail + senha — use uma conta de agente dedicada na sua instância Relay.

{
  "mcpServers": {
    "evc-relay": {
      "command": "uvx",
      "args": ["evc-team-relay-mcp"],
      "env": {
        "RELAY_CP_URL": "https://cp.yourdomain.com",
        "RELAY_AGENT_KEY": "tr_agent_your_key_here"
      }
    }
  }
}

{
  "mcpServers": {
    "evc-relay": {
      "command": "uvx",
      "args": ["evc-team-relay-mcp"],
      "env": {
        "RELAY_CP_URL": "https://cp.yourdomain.com",
        "RELAY_EMAIL": "agent@yourdomain.com",
        "RELAY_PASSWORD": "your-password"
      }
    }
  }
}

{
  "mcp_servers": {
    "evc-relay": {
      "type": "stdio",
      "command": "uvx",
      "args": ["evc-team-relay-mcp"],
      "env": {
        "RELAY_CP_URL": "https://cp.yourdomain.com",
        "RELAY_AGENT_KEY": "tr_agent_your_key_here"
      }
    }
  }
}

{
  "mcpServers": {
    "evc-relay": {
      "command": "uvx",
      "args": ["evc-team-relay-mcp"],
      "env": {
        "RELAY_CP_URL": "https://cp.yourdomain.com",
        "RELAY_AGENT_KEY": "tr_agent_your_key_here"
      }
    }
  }
}

"command": "uv",
"args": ["run", "--directory", "/path/to/evc-team-relay-mcp", "relay_mcp.py"]

Variáveis de ambiente:

Modelos de configuração prontos para copiar também estão em config/.

3. Use

Seu agente de IA agora tem estas ferramentas:

Fluxo de trabalho típico: list_shares -> list_files -> read_file / upsert_file

A autenticação é automática — o servidor faz login e renova tokens internamente.

Matriz de disponibilidade de ferramentas

Nem toda ferramenta funciona em todos os modos de autenticação, e um grupo não funciona em nenhum modo — são dois fatos não relacionados, então não os confunda:

• O acesso de escrita é somente com chave de agente, por política sancionada (veja TR-05 (#0cdd5328)): upsert_file é a única ferramenta de escrita com rota de backend funcional, e ela só escreve quando uma chave de agente (RELAY_AGENT_KEY / RELAY_AGENT_KEYS) está configurada. Chamar upsert_file no modo JWT gera um ValueError claro indicando o modo chave de agente como solução, em vez de um 404 confuso.
• read_document, write_document e delete_file são uma lacuna separada e independente — o plano de controle não tem rota de backend para eles de forma alguma, nem no modo chave de agente. Trocar para uma chave de agente não fará com que funcionem: o conteúdo ao vivo de compartilhamentos de documentos é somente CRDT/WebSocket (sem ponte REST), e a exclusão por arquivo não tem rota DELETE no servidor ainda. Se rotas para esses forem adicionadas no futuro, elas ainda seguiriam a política de escrita somente com chave de agente acima — JWT permaneceria somente leitura.

Implantação Remota (Transporte HTTP)

Para implantações compartilhadas ou do lado do servidor, execute como um servidor HTTP:

# Direct
uv run relay_mcp.py --transport http --port 8888

# Docker (pulls from Docker Hub automatically)
RELAY_CP_URL=https://cp.yourdomain.com \
RELAY_EMAIL=agent@yourdomain.com \
RELAY_PASSWORD=your-password \
docker compose up -d

# Or pull explicitly
docker pull deadalusevc/evc-team-relay-mcp:latest

Por padrão, o servidor vincula-se a 127.0.0.1 (somente localhost) — o endpoint não é acessível pela rede, mesmo que o host tenha um IP público. Isso corresponde ao caso comum de um único cliente MCP na mesma máquina que o servidor.

Em seguida, configure seu cliente MCP para conectar via HTTP:

{
  "mcpServers": {
    "evc-relay": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:8888/mcp"
    }
  }
}

Acesso remoto via túnel SSH (recomendado)

Se seu cliente MCP roda em uma máquina diferente do servidor, faça um túnel para a porta vinculada ao localhost em vez de expô-la publicamente:

# From the client machine, forward local 8888 to the server's localhost:8888
ssh -N -L 8888:127.0.0.1:8888 user@your-server

Depois aponte a configuração do cliente para http://127.0.0.1:8888/mcp como acima — o tráfego passa pelo túnel SSH, e o endereço de vinculação do servidor nunca precisa mudar.

Vinculação pública / proxy reverso (opt-in)

Se você realmente precisar que o servidor aceite conexões de outros hosts diretamente (por exemplo, atrás de um proxy reverso que termina TLS e lida com autenticação), passe --host explicitamente:

uv run relay_mcp.py --transport http --port 8888 --host 0.0.0.0

Faça isso somente atrás de um proxy reverso ou firewall — o endpoint HTTP do MCP não tem autenticação embutida, então vinculá-lo a 0.0.0.0 em uma rede aberta expõe todas as chamadas de ferramentas do relay a qualquer pessoa que alcance a porta.

Segurança

O servidor MCP oferece vantagens significativas de segurança em relação a integrações baseadas em shell:

• Sem execução de shell — todas as operações são chamadas de funções Python via JSON-RPC, eliminando riscos de injeção de comandos
• Sem argumentos de CLI — credenciais e tokens nunca são passados como argumentos de processo (invisíveis na saída de ps)
• Gerenciamento automático de tokens — o servidor lida com login, renovação de JWT e ciclo de vida de tokens internamente; o agente nunca toca em tokens brutos
• Entradas tipadas — todos os parâmetros são validados contra o JSON Schema antes da execução
• Processo único persistente — sem spawn de shell por chamada, sem vazamento de ambiente entre invocações

Nota: Se você está usando a habilidade OpenClaw (scripts bash), considere migrar para este servidor MCP para uma integração mais segura e sustentável.

Como Funciona

┌─────────────┐      MCP        ┌──────────────┐     REST API     ┌──────────────┐     Yjs CRDT      ┌──────────────┐
│  AI Agent   │ ◄────────────► │  MCP Server  │ ◄─────────────► │  Team Relay  │ ◄──────────────► │   Obsidian   │
│ (any tool)  │  stdio / HTTP  │ (this repo)  │    read/write   │   Server     │    real-time     │    Client    │
└─────────────┘                └──────────────┘                 └──────────────┘      sync         └──────────────┘

O servidor MCP encapsula a API REST do Team Relay em ferramentas MCP padrão. O Team Relay armazena documentos como CRDTs Yjs e os sincroniza com clientes Obsidian em tempo real. Alterações feitas pelo agente aparecem no Obsidian instantaneamente — e vice-versa.

Pré-requisitos

• Python 3.10+ com uv (recomendado) ou pip
• Uma instância EVC Team Relay em execução (auto-hospedada ou hospedada)
• Uma conta de usuário no plano de controle do Relay

Parte de Todo o Kit de Ferramentas VC

Comunidade

• entire.vc
• Discussões
• support@entire.vc
• Onde obter ajuda e o que esperar

Licença

MIT