> For the complete documentation index, see [llms.txt](https://help.calshare.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.calshare.net/portugues/integracao-com-o-servidor-mcp.md).

# Integração com o servidor MCP

Conecte dados e ferramentas do Calshare diretamente a Agentes de IA externos usando o Model Context Protocol.

### 7.1. Visão Geral da Arquitetura

O \*\*Servidor Calshare Model Context Protocol (MCP)\*\* faz a ponte entre a plataforma interna de agendamento da Calshare e Agentes de IA modernos (como Cursor, Claude Desktop e Gemini).

Ao conectar-se a este servidor MCP, os agentes obtêm acesso autônomo a calendários, faixas de disponibilidade em tempo real e a capacidade de marcar compromissos diretamente via API.

O Servidor MCP é uma aplicação Node.js leve que executa na mesma infraestrutura do backend do Calshare. Ele utiliza o oficial `@modelcontextprotocol/sdk` e atua como uma camada de tradução:

Agente de IA <---> \[STDIO] <---> Servidor MCP Node.js <---> \[HTTP REST V1] <---> Banco de Dados MySQL do Calshare

**Transporte de conexão:** O servidor está configurado para se comunicar via \*\*STDIO\*\*. Isso significa que ele deve ser invocado como um subprocesso pelo Cliente MCP (por exemplo, o seu IDE ou Aplicativo de Desktop).

### 7.2. Configurando o Claude Desktop ou o Cursor

Para dar ao seu Agente de IA acesso aos dados do Calshare, você deve configurar o Cliente MCP para iniciar este servidor.

1

**Abra o arquivo de configurações do seu Cliente MCP:**

* **Claude Desktop:** `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Cursor:** Vá para Configurações > Recursos > MCP > Adicionar novo servidor MCP.

2

**Adicione a seguinte configuração do servidor:**

```
{
  "mcpServers": {
    "calshare-mcp": {
      "command": "node",
      "args": [
        "/var/www/nurank.org/mcp-server/index.js"
      ]
    }
  }
}
```

> **Nota sobre tunelamento SSH:** Se você estiver executando o cliente MCP na sua máquina local, mas o servidor for remoto, você pode encaminhar a execução via SSH:
>
> "command": "ssh", "args": \["<root@calshare.net>", "node", "/var/www/nurank.org/mcp-server/index.js"]

### 7.3. Ferramentas Disponíveis (Funções)

O servidor expõe três ferramentas principais. Os agentes descobrirão essas ferramentas automaticamente quando conectados.

#### A. `get_calendars`

Recupera todos os calendários ativos disponíveis no sistema.

* **Entrada:** Nenhum
* **Saída:** Array JSON contendo objetos de calendário (ID, nome, tema, booking\_slug, configurações).

#### B. `get_available_slots`

Consulta o mecanismo de reservas para obter faixas de horário disponíveis em uma data fornecida, calculando tempos de buffer, durações e capacidades de slots concorrentes.

* **Parâmetros de entrada:**
  * `calendar_id` (Número) - O ID do calendário.
  * `date` (String) - Data de destino em `YYYY-MM-DD` formato.
* **Saída:** Array JSON de horários disponíveis (por exemplo, `["09:00", "09:45", "10:30"]`).

#### C. `create_booking`

Cria uma reserva confirmada para um usuário.

* **Parâmetros de entrada:**
  * `calendar_id` (Número) - O ID do calendário.
  * `datetime` (String) - A data e a hora exatas da reserva (`YYYY-MM-DD HH:MM:SS`).
  * `name` (String) - Nome do cliente.
  * `email` (String) - E-mail do cliente (opcional).
  * `service_names` (String) - Descrição dos serviços solicitados (opcional).
* **Saída:** Mensagem de sucesso e `event_id`.

### 7.4. Estendendo o Servidor MCP

Se você precisar adicionar novas capacidades (por exemplo, `cancel_booking` ou `get_reminders`), siga estas etapas:

1

Abra `/var/www/nurank.org/mcp-server/index.js`.

2

Adicione o esquema da nova ferramenta dentro do manipulador `ListToolsRequestSchema` .

3

Adicione o caso correspondente na instrução `CallToolRequestSchema` switch, fazendo uma `apiClient` solicitação ao endpoint apropriado da API V1.

4

Reinicie o cliente MCP para atualizar as ferramentas.

**⚠️ Aviso de Segurança e Autenticação:** O Servidor MCP usa uma `MASTER_API_KEY` definida internamente para autenticar com o endpoint `/api/v1/auth.php` . Ele opera em nome do `sistema` usuário, concedendo acesso administrativo a todos os calendários. Não exponha esta chave.

<br>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.calshare.net/portugues/integracao-com-o-servidor-mcp.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.