<!-- Connecting your own AI tool via MCP -->
<!-- canonical: https://plainwater.ai/en/wiki/eigen-ai/mcp-koppelen -->
# Connecting your own AI tool via MCP

Plainwater AI has an MCP server for people. With it you connect your own AI tool to the platform: Claude Code, Codex, or
another tool that speaks MCP, such as GitHub Copilot in VS Code or Cursor. You sign in with OAuth; there is no API key to
paste anywhere.

## Two connections

| Connection | Path | What you get |
| --- | --- | --- |
| **Together** | `/mcp/user` | Your AI directs; heavy work can be handed over to platform agents |
| **Solo** | `/mcp/solo` | Everything in your AI; the platform incurs no model costs |

The difference is the tool list. An AI tool requests its list of tools once per connection. That is why these are two
connections rather than one connection with a switch. A token only works on the path it was issued for.

## Requirements

- You have an account with access to the customer you want to work for.
- The customer allows local sessions. This is **off** by default and is switched on per customer in the ground rules.
- Your AI tool supports MCP over HTTP with OAuth.

## Configuration example

A generic example for an MCP client that reads a JSON configuration:

```json
{
  "mcpServers": {
    "plainwater": {
      "type": "http",
      "url": "https://app.plainwater.ai/mcp/user"
    },
    "plainwater-solo": {
      "type": "http",
      "url": "https://app.plainwater.ai/mcp/solo"
    }
  }
}
```

For Claude Code a single command does it:

```bash
claude mcp add --transport http plainwater https://app.plainwater.ai/mcp/user
```

:::warning Check the URL in the app
The addresses above are examples. The exact URL for your environment is in the web app, in your profile under the
instructions for local sessions.
:::

## Signing in

1. Add the server to your AI tool.
2. On the first call your tool opens a browser window.
3. You sign in with your organisation account (Microsoft Entra ID).
4. You give consent. The tool receives a short-lived access token valid only for this connection, plus a refresh token
   that rotates on every use.

The token itself carries no permissions. On every call the platform reads from the database again who you are and what
you may do. If an administrator revokes your rights, that applies from your next call.

## Starting a session

Once connected, your AI works inside a **session** on a work item:

1. Your AI requests the list of your work items, or creates a new one.
2. It starts a session on that work item.
3. It chooses the sources that belong to the work item, and within those the source it works on.
4. It uses the tools: metadata, quality, performance, sandbox, and (if the source allows it) SQL.
5. It ends the session, or hands the work over to the platform.

One active session runs per authorisation at a time.

## What your AI gets to see

Your AI gets the same as a platform agent: names as pseudonyms for a customer with real data, values according to the
source's setting, counts below ten as "<10". Of a source your AI only sees a label chosen by the administrator, never the
technical name.

## Example

A developer adds `plainwater` to Claude Code and signs in. He asks: "Which work items are open for customer X?" Claude
Code shows the list, starts a session on the work item "slow nightly load" and picks the source *warehouse-prod*. It
fetches the heaviest queries and the missing indexes, proposes an index and tests it in a disposable copy. The result
then appears as a deliverable on the work item in the web app.

:::tip Read on
- [Three ways of working compared](https://plainwater.ai/en/wiki/eigen-ai/werkwijzen)
- [Solo](https://plainwater.ai/en/wiki/eigen-ai/solo)
- [Ground rules per customer](https://plainwater.ai/en/wiki/beheer/spelregels)
:::