# Connect AI tools

> Let an AI tool such as Cursor, Claude Code or VS Code read and update your SAPUGO data over MCP, with its own identity, limited access and your approval where it matters.

SAPUGO can talk to the AI tools your team already works in. An AI tool connects with an API key, and then it can look up records, answer questions about your data and, if you allow it, create and change records, build tables and views, and run workflows.

The connection uses the Model Context Protocol (MCP), an open standard that most AI coding tools and agent frameworks support. You don't write any code. You create an application in SAPUGO, decide what it may do, and paste a short connection snippet into the AI tool.

## What the tool can reach

An AI tool is never more powerful than the person who set it up, and never more powerful than you allow.

- It signs in as an **application**, its own identity in your organization. It sees only the views that are shared with that application, with the same [access rules](/docs/access), hidden columns and row filters that apply to people.
- You choose what the application may do with **scopes**: read, write records, change the structure, run workflows, and so on. A scope you don't grant isn't offered to the tool at all. See [Control what a tool may do](/docs/ai-tools/access).
- Steps that change who can see what, or that send data out of your organization, wait for a person's approval.
- Every call is written to the application's **Agent activity** list.

## Standard and advanced access

| | Standard | Advanced |
| --- | --- | --- |
| Read records, comments and change history | Yes | Yes |
| Create, update and delete records, add comments | Yes | Yes |
| Totals and summaries over a view | | Yes |
| Change tables, columns, views, layouts, pages, dashboards, documents and business rules | | Yes |
| Create and run workflows, and decide approval requests | | Yes |
| Hand a request to the SAPUGO assistant | | Yes |

Standard access covers the **Read records and history** and **Create and change records** scopes. Advanced access unlocks the remaining scopes. The full list is in [Tools and limits](/docs/ai-tools/tools).

> **Note:** Standard access is included on every plan and is ready to use. Advanced access is switched on for each organization. Until it is on, the advanced scopes are greyed out in your application settings. To get it, write to hello@sapugo.com with the name of your organization.

## Set up a connection

> **Tip:** Prefer to be guided? Ask the SAPUGO assistant to connect an AI tool. It checks your existing connections, creates the application, allows it to connect, shares the groups you choose and sets read-only or read and write. You issue the API key yourself in the last step, so the secret never appears in the chat.

1. Open **Settings**, choose **Developer Tools**, then **Applications**, and click **Set up connection** in the **Connect an AI tool** box. Give it a name such as "Cursor for the office team". SAPUGO creates the application and gives it the permission **External AI tools**, which it needs to connect.
2. The application opens with a **Setup checklist** that shows what is still missing: the permission, shared data, an API key, and a first request from your tool. Use it as your guide for the next steps.
3. Share the data it needs. Add the application to a [group](/docs/groups), then give that group access to the views it should use. A view the application can't open is invisible to the tool.
4. In the **AI tool access** section, under **What this application may do**, choose the scopes. A new application can only read. Add **Create and change records** if the tool should write. Click **Save access limits**.
5. Under **API keys**, enter a **Label**, set **Expires (days)** if the key should stop working on its own, and click **Issue key**.
6. Copy the secret now. It's shown only once and is stored only as a one-way hash, so it can't be shown again. If you lose it, revoke the key and issue a new one. Under the secret, SAPUGO shows connection snippets for Cursor, Claude Code and VS Code with your address and the new key already filled in.

> **Warning:** Treat the key like a password. Anyone who has it can do what the application may do. Keep it out of shared documents and source code, and revoke it if it leaks.

## Connect your AI tool

Every connection needs two things: the address of your organization and the API key.

- **Address:** `https://your-organization.eu.sapugo.app/api/core/v1/mcp`, using the address you open SAPUGO at.
- **Header:** `Authorization: Bearer your-api-key`.
- **Optional header:** `x-database-id` with the id of a database, if your organization has several. Leave it out to use the default database.

In **AI tool access** in the application's settings, pick your tool and click **Copy connection** for a ready-made snippet with your address filled in. Replace `<api-key>` with your key. If your organization has several databases, the snippet also has an `x-database-id` line: set it to the database you want, or delete it to use the default database. Once your tool has made its first request, the last step of the **Setup checklist** turns green.

### Cursor

Add this to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` for all projects.

```json
{
  "mcpServers": {
    "sapugo": {
      "url": "https://your-organization.eu.sapugo.app/api/core/v1/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add --transport http sapugo \
  https://your-organization.eu.sapugo.app/api/core/v1/mcp \
  --header "Authorization: Bearer your-api-key"
```

### VS Code

Add this to `.vscode/mcp.json`.

```json
{
  "servers": {
    "sapugo": {
      "type": "http",
      "url": "https://your-organization.eu.sapugo.app/api/core/v1/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key"
      }
    }
  }
}
```

### Other tools

Any tool that supports MCP over HTTP and lets you set a request header can connect. Use the address and header above. SAPUGO answers each request on its own and keeps no session, so there is nothing to keep alive and a dropped connection costs nothing.

## Try it

Once connected, the tool lists the views it can read. Ask in plain words:

- "Which orders from Acme Ltd are still open?"
- "Add a comment to the quote for Müller GmbH saying the customer called back."
- "How many support requests came in per week this month?" (advanced access)

The tool gets a short description of your views when it connects, so it knows which tables and fields exist before you ask.

> **Tip:** Start with read-only access and one view. Watch **Agent activity** for a few days, then add scopes as you gain trust in what the tool does.

## Safe by design

- **Your rules still apply.** A tool can't read a hidden column or a row outside the view's filter, even when asked.
- **Stored text is data.** Text inside your records is returned to the tool marked as stored content, not as instructions. Even so, be careful which tools you point at records that outsiders can fill in, such as form submissions.
- **Risky steps stop for you.** Deleting a table or column needs an explicit confirmation from the tool, and a backup is taken first where data could be lost. Changes that send data out of your organization wait for a person to approve them.
- **Limits per key.** One busy tool can't use up what the rest of your team needs. See [Tools and limits](/docs/ai-tools/tools#limits).
- **EU hosted.** Calls are handled in the same EU data region as the rest of your workspace.

  - [Control what a tool may do](/docs/ai-tools/access): Scopes, databases, allowed addresses, approvals and activity.
  - [Tools and limits](/docs/ai-tools/tools): Every tool a connection can offer, and the limits that apply.
  - [Access](/docs/access): The rules that decide what an application can see.
  - [Groups](/docs/groups): Give an application the same access as a team.

---

Source: https://community.sapugo.app/docs/ai-tools