Skip to main content

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​

ConnectionPathWhat you get
Together/mcp/userYour AI directs; heavy work can be handed over to platform agents
Solo/mcp/soloEverything 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:

{
  "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:

claude mcp add --transport http plainwater https://app.plainwater.ai/mcp/user
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.

Read on