> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.basement.chat/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.basement.chat/_mcp/server.

# Serviços conectados

Um serviço conectado é um sistema fora do Basement que sua organização usa: uma central de serviços, um gerenciador de demandas, uma base de conhecimento. Uma pessoa conecta uma conta do serviço em **Conexões**. Depois disso, agentes e programas usam as ferramentas desse serviço pelo Gateway.

## Serviços que você pode conectar

| Serviço                   | O que uma chave pode fazer                                                                                                                          |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Jira** (e Confluence)   | Buscar e ler itens e páginas, criar e alterar. Entre com a conta Atlassian, ou use e-mail e token de API.                                           |
| **GLPI**                  | Buscar e ler chamados, a base de conhecimento e usuários. Criar chamados, adicionar acompanhamentos e soluções, alterar e atribuir chamados.        |
| **MultiDados**            | Buscar e ler chamados com o histórico e os anexos. Criar chamados, responder, mudar a situação e agendar uma resposta ou uma alteração para depois. |
| **Qualquer servidor MCP** | Conecte um servidor com token, cabeçalhos próprios ou OAuth. As ferramentas dele ficam disponíveis pelo Gateway.                                    |

Um administrador configura o serviço uma vez para a organização. Depois, cada membro conecta a própria conta, e os agentes dele agem como ele.

## Qual conta a chave usa

Uma conexão é privada de quem conectou, ou compartilhada com a organização. Uma chave usa as conexões que a pessoa que conectou a chave pode usar. Uma chave nunca alcança a conexão privada de outra pessoa.

Em uma central de serviços, isso quer dizer que um agente vê os chamados que a pessoa dele vê, e escreve como essa pessoa.

## Leitura e escrita

Cada ferramenta de um serviço é de leitura ou de escrita. Um nível de acesso dá à chave **leitura**, ou **leitura e escrita**, em cada serviço:

* Com **leitura**, a chave lista as ferramentas do serviço e chama as de leitura. Uma ferramenta de escrita responde `403`.
* Com **leitura e escrita**, a chave chama todas as ferramentas.

## Como chamar um serviço

Três ferramentas dão acesso a todos os serviços conectados:

### Liste os serviços

`list_connected_services` responde os serviços que a chave pode usar, e cada conexão com o `connectionId` dela.

### Liste as ferramentas de um serviço

`list_service_tools` responde as ferramentas de um serviço. Cada ferramenta tem um `toolSlug` (por exemplo, `jira__getJiraIssue`), uma descrição, o esquema dos argumentos, se é de leitura ou escrita, e se esta chave pode chamar.

### Execute uma ferramenta

`execute_service_tool` executa uma ferramenta. Informe o `toolSlug` e os `arguments` da ferramenta.

**`TypeScript`**

```typescript title="TypeScript"
const { tools } = await basement.services.listTools({ toolkitSlug: "jira" });

const result = await basement.services.execute({
  toolSlug: "jira__getJiraIssue",
  arguments: { issueIdOrKey: "OPS-12" },
});
```

**`Python`**

```python title="Python"
tools = basement.services.list_tools(toolkit_slug="jira").tools

result = basement.services.execute(
    tool_slug="jira__getJiraIssue",
    arguments={"issueIdOrKey": "OPS-12"},
)
```

A resposta é o que o serviço respondeu. Quando o serviço falha ou recusa a chamada, a API HTTP responde `502` com a mensagem do serviço.