> 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.

# Connected services

A connected service is a system outside Basement that your organization uses: a service desk, an issue tracker, a knowledge base. A person connects an account of the service in **Connections**. After that, agents and programs can use the tools of that service through the Gateway.

## Services you can connect

| Service                   | What a key can do                                                                                                                             |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **Jira** (and Confluence) | Search and read issues and pages, create and change them. Sign in with Atlassian, or use an email and an API token.                           |
| **GLPI**                  | Search and read tickets, the knowledge base and users. Create tickets, add follow-ups and solutions, change and assign tickets.               |
| **MultiDados**            | Search and read tickets with their history and attachments. Create tickets, reply, change status, and schedule a reply or a change for later. |
| **Any MCP server**        | Connect a server with a token, custom headers or OAuth. Its tools become available through the Gateway.                                       |

An admin sets a service up one time for the organization. Then each member connects their own account, and their agents act as them.

## Whose account a key uses

A connection is private to the person who made it, or shared with the organization. A key uses the connections that the person who connected the key can use. A key never reaches another person's private connection.

For a service desk, this means an agent sees the tickets that its person sees, and writes as that person.

## Read and write

Each tool of a service is a read tool or a write tool. An access level gives a key **read**, or **read and write**, for each service:

* With **read**, the key lists the service's tools and calls the read tools. A write tool answers `403`.
* With **read and write**, the key calls every tool.

## How to call a service

Three tools give access to every connected service:

### List the services

`list_connected_services` answers the services the key can use, and each connection with its `connectionId`.

### List the tools of a service

`list_service_tools` answers the tools of one service. Each tool has a `toolSlug` (for example `jira__getJiraIssue`), a description, the schema of its arguments, whether it reads or writes, and whether this key can call it.

### Run a tool

`execute_service_tool` runs a tool. Give the `toolSlug` and the tool's `arguments`.

**`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"},
)
```

The answer is what the service answered. When the service fails or refuses the call, the HTTP API answers `502` with the service's message.