# Cursor

Conecte o Cursor IDE por meio de Browser OAuth como o caminho preferencial, com MCP direto como alternativa headless compatível.

- Canonical: https://docs.xmemo.dev/pt-br/docs/mcp/cursor
- Locale: pt-BR
- Content-Locale: pt-BR
- Canonical-Content-Digest: 7fd7191e1dc893d17ccc57d383768ec709f689feebde935e92cbec85252ab1df
- Edition-Digest: f3ea9d27e57fd40cd0a19f07a7926bfa1fe4c88a505cdfa092d2689567c28ec4
- Source-Revision: sha256:5900c57d4a9131e42571635160707dd33bcf4854c638661503d89ccec7e4bdeb

## Pré-requisitos

Use o Cursor IDE com Configurações -> Recursos -> MCP ou suporte do marketplace. Interface e pré-requisitos:

- Interface concreta: Cursor IDE (~/.cursor/mcp.json ou Configurações -> Recursos -> MCP).
- Endpoint: https://xmemo.dev/mcp.
- Modo de autenticação preferencial: Browser OAuth.
- Modo de autenticação alternativo: Token de portador direto para ambientes headless e contêineres.
- Conta: Conta válida do XMemo em https://xmemo.dev.

## Instalação / configuração

Abra Cursor Configurações -> Recursos -> MCP ou configure ~/.cursor/mcp.json. Para operação headless, use o bloco de configuração direta com referência de token de ambiente em vez do fluxo do navegador:

- Caminho OAuth: Configure apenas a URL hospedada e deixe o primeiro uso acionar o consentimento do navegador.
- Alternativa direta: Mantenha o token em XMEMO_KEY, nunca diretamente no arquivo de configurações.
- Não misture a configuração de URL OAuth com um cabeçalho Authorization na mesma entrada.

## Definir a credencial

O caminho OAuth não requer chave — conclua o Browser OAuth no primeiro prompt. Para a alternativa headless direta, defina XMEMO_KEY no ambiente de shell e nunca cole valores de token nas configurações do Cursor:

```bash
# OAuth path: no XMEMO_KEY needed (browser prompt)
# Direct fallback:
export XMEMO_KEY='<your-xmemo-token>'
```

## Gerar / confirmar XMEMO_AGENT_INSTANCE_ID

Os trechos de código revisados de OAuth e direto do Cursor não exigem um cabeçalho de instância no lado do cliente. Se um wrapper headless fornecer XMEMO_AGENT_INSTANCE_ID, gere-o uma vez por perfil local e reutilize-o.

## Preservar o bloco de configuração existente

Caminho OAuth preferencial: Use a configuração revisada do Cursor de apenas URL em ~/.cursor/mcp.json para autenticação OAuth baseada em navegador:

```json
{
  "mcpServers": {
    "xmemo": {
      "url": "https://xmemo.dev/mcp"
    }
  }
}
```

## Bloco de configuração de fallback direto

Fallback direto headless: Ao executar o Cursor em ambientes headless ou não interativos, configure o cabeçalho Authorization referenciando ${env:XMEMO_KEY} do seu ambiente local:

```json
{
  "mcpServers": {
    "xmemo": {
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:XMEMO_KEY}"
      }
    }
  }
}
```

## Reiniciar o cliente

Reinicie o Cursor ou desative e ative o servidor MCP em Configurações -> Recursos -> MCP após editar a configuração para que as alterações tenham efeito.

## Testar com uma chamada real de recall

Faça a primeira chamada MCP somente leitura. Esta é uma invocação real de recall, não um espaço reservado para verificação de integridade, e não grava na memória.

```text
recall({ query: "connection check", limit: 1 })
```

## Resposta esperada (formato literal)

Uma chamada bem-sucedida retorna o formato de texto classificado público abaixo; a referência e o conteúdo são valores reais do espaço de memória autorizado.

```text
### XMemo Memory Results:
1. Reference: <opaque-memory-id> | Location: <location>
   > <memory content>
```

## Primeira tarefa útil: Ciclo de vida de memória sintética

Exercite a tarefa completa de memória sintética dentro do Cursor Composer ou modo Agent:

- 1. Salvar fato sintético: Peça ao Cursor para lembrar da convenção ("Demo project timestamps use UTC.") em "projects/demo-onboarding/conventions".
- 2. Transição sem estado: Inicie um novo chat no Cursor Composer ou reabra o espaço de trabalho do projeto.
- 3. Recall com atribuição de fonte: Consulte "demo project timestamp format". Confirme Reference e Location retornados.
- 4. Corrigir memória: Chame update_memory com o ID ativo para formatar os registros de data e hora com ISO 8601.
- 5. Limpeza opcional: Chame forget com o ID da memória quando os testes de integração forem concluídos.

## Recursos e ferramentas de perfil

O Cursor tem acesso a ferramentas qualificadas por perfil definidas no contrato de documentação do MCP para o perfil cursor-plugin:

- Ferramentas de memória principais: remember, recall, update_memory, forget, read_memory, explain_memory, search_memory, recall_context, search_knowledge.
- Ferramentas de instantâneos e conflitos: create_restart_snapshot, restore_restart_snapshot, list_memory_versions, list_memory_conflicts, resolve_memory_conflict.
- Ferramentas de projeto e planejamento: get_mcp_identity, get_project_context, get_timeline, list_memory_todos, complete_memory_todo, create_memory_todo, update_project_decision, update_project_todo, update_state.
- Skills em nuvem e governança: recall_cloud_skill, save_cloud_skill, propose_write, propose_todo_mutation, propose_profile_mutation, query_audit, record_event, memory_stats.

## Limitações e limites

Limites operacionais e restrições para o Cursor:

- Pureza de configuração: Não misture a configuração apenas de URL OAuth com um cabeçalho Authorization no mesmo bloco de servidor.
- Limite do espaço de trabalho: O acesso à memória é estritamente limitado ao espaço de trabalho do usuário autenticado.
- Requisito de token headless: O fallback de MCP direto requer o provisionamento explícito de token de ambiente.

## Erros comuns

O Cursor pode falhar no seu caminho OAuth ou no seu fallback headless direto:

- invalid_grant — O código de autorização OAuth é inválido, expirou ou já foi usado: reconecte o Cursor e autorize novamente.
- 401 invalid_token — O token de fallback direto está ausente, expirado ou inválido: verifique XMEMO_KEY no ambiente headless.
- 403 insufficient_scope — A credencial não concede memory:read: aprove o escopo necessário ou emita um token com ele.

## Atualização e remoção

Procedimentos de manutenção para o Cursor:

- Atualização: Desative e ative o servidor nas configurações de MCP do Cursor para recarregar esquemas.
- Remoção: Exclua a entrada xmemo de ~/.cursor/mcp.json ou remova-a das configurações de MCP do Cursor.

## Cursor

Direct client: configure in ~/.cursor/mcp.json with XMEMO_KEY in the environment. Run npx @xmemo/client mcp add cursor to install automatically.

```
{
  "mcpServers": {
    "XMemo": {
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:XMEMO_KEY}",
        "X-Memory-OS-Agent-ID": "cursor",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}
```