MCP server

What is the MCP server?

The MCP server lets you connect AI assistants to Tidal Control. Once connected, your assistant can search your compliance data, create and update records, manage relationships between entities, and summarise KPIs — all from a normal conversation.

Your existing Tidal Control permissions apply. If you only have read access in the portal, your assistant can only read.

What you can do

Once connected, you can ask your AI assistant to help with your compliance work in Tidal Control. Here are some examples of what's possible.

Answer questions about your compliance data

• "How many high-severity risks don't have any controls linked to them?"
• "Show me all vendors with overdue assessments."
• "Which ISO 27001 requirements aren't covered by any of our controls?"
• "What's the pass rate of our automated tests this month?"

Get KPIs and statistics

• "Summarise our framework compliance for SOC 2."
• "How many assets are assigned, assessed, and compliant?"
• "Give me the status of all issues created in the last 30 days."

Make bulk changes you'd normally click through

• "Create issue tasks for each of these 12 audit findings and link them to control AC-01."
• "Archive all vendor assessments that expired more than a year ago."
• "Add Server-1, Server-2, and Server-3 to the 'Quarterly Access Review' plan."

Link things together

• "Link controls CC6.1 through CC6.8 to risk R-042."
• "Attach backup-policy.pdf as evidence to this quarter's backup verification execution."
• "Add a reference from ISO 27001 A.8.1 to our Access Control Policy control."

Search documents by meaning

• "Which of our policies mentions remote work expectations?"
• "Find the document that describes our incident response timeline."

Context-aware prompts

Your assistant knows who you are, which organisation you're in, and today's date — so you can say things like "what's due next week for me?" without spelling out names or dates.

Before you start

You'll need your organisation ID. It's the part of the portal URL you log in with. For example, if you sign in at portal.tidalcontrol.com/acme/..., your organisation ID is acme.

Replace <organisation-id> in the URLs below with your own.

Connecting

Claude Desktop

1. In the message box (where you type your prompts), click the + button
2. Go to Connectors → Manage connectors
3. Click the + next to Connectors → Add custom connector
4. Fill in:
   • Name: Tidal Control
   • Remote MCP server URL: https://mcp.tidalcontrol.com/<organisation-id>
5. Sign in when your browser opens

Claude Code

Run this in your terminal:

claude mcp add tidalcontrol --transport http https://mcp.tidalcontrol.com/<organisation-id>

A browser window opens for you to sign in. After that, the connection is ready.

Codex

Register the server and sign in:

codex mcp add tidalcontrol --url https://mcp.tidalcontrol.com/<organisation-id>
codex mcp login tidalcontrol

Any MCP client

Any client that supports MCP over Streamable HTTP with OAuth 2.1 can connect. Point it at https://mcp.tidalcontrol.com/<organisation-id>. The server advertises its OAuth endpoints via RFC 9728 and supports Dynamic Client Registration (RFC 7591), so most clients can discover everything automatically.

How it works

When you connect, your AI tool discovers how to authenticate with Tidal Control. You sign in once through your browser using your normal Tidal Control credentials. After that, the connection stays active under your identity.

Your permissions apply. The assistant can only do what your role in the portal allows. A read-only user cannot create or change records through MCP, just like in the portal.

Areas the MCP server covers

The MCP server exposes tools across all major areas of Tidal Control:

| Area | What your assistant can do | |------|----------------------------| | Risks | Search, create, update, archive, delete. Manage risk assessments. Link to controls and assets. | | Controls | Search, create, update, archive, delete. Link to assets, risks, plans, and framework references. | | Assets | Search, create, update, archive, delete. Set CIA scores, RTO/RPO, and target service levels. Link to controls, risks, and plans. | | Tasks | Search, create, update, close, reopen, delete issues, assessments, and executions. Link to controls and assets. | | Comments | Add, update, and delete comments on tasks. | | Evidence | Link documents as evidence to tasks. | | Documents | Search by filter or by meaning (semantic). Create, update, delete. | | Document classifications | List, create, update, approve, and delete classifications linking documents to types. | | Required documents | List the documents required by your frameworks. | | Frameworks | Browse frameworks (ISO 27001, SOC 2, GDPR, and more) and their references. | | Plans | Search, create, update, archive, delete. Link to assets and controls. Manage activity configurations on a plan. | | Vendors | Search, create, update, archive, delete. Manage vendor assessments. | | Personnel | Search persons, groups, and platform users. Create and delete persons and groups. | | Tests | Browse automated tests and their results. | | Insights & KPIs | Get KPIs for assets, personnel, and vendors. Get statistics for tests, activities, and framework compliance. | | Context | Look up the current user, current organisation, and the current date and time in your timezone. |

Linking entities

You can ask your assistant to link entities together, for example:

• "Link control AC-01 to risk R-003"
• "Add assets Server-1 and Server-2 to plan Quarterly Access Review"
• "Remove the reference to ISO 27001 A.8.1 from this control"

These actions add or remove individual links without affecting other existing relationships.

For developers

Programmatic access (Device Authorization flow)

For automated agents and scripts that cannot open a browser, use the OAuth Device Authorization Grant (RFC 8628):

Step 1: Request a device code

curl -s -X POST https://auth.tidalcontrol.com/realms/<organisation-id>/protocol/openid-connect/auth/device \
  -d "client_id=portal" \
  -d "scope=openid email profile roles portal-roles offline_access"

Response:

{
  "device_code": "abc123...",
  "user_code": "ABCD-EFGH",
  "verification_uri": "https://auth.tidalcontrol.com/realms/<organisation-id>/device",
  "expires_in": 600,
  "interval": 5
}

Step 2: Authenticate in a browser

Open the verification_uri, enter the user_code, and sign in. This only needs to happen once — store the refresh token for future sessions.

Step 3: Poll for a token

curl -s -X POST https://auth.tidalcontrol.com/realms/<organisation-id>/protocol/openid-connect/token \
  -d "client_id=portal" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:device_code" \
  -d "device_code=abc123..."

Returns authorization_pending until the user approves. Once approved:

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "expires_in": 300,
  "refresh_expires_in": 1800
}

Step 4: Connect to MCP

curl -X POST https://mcp.tidalcontrol.com/<organisation-id> \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"method":"initialize","params":{...},"jsonrpc":"2.0","id":0}'

Refresh the token before it expires. The token carries your user identity and permissions.

Pagination

Search tools return paginated results with content, hasNext, and totalElements. Control pagination with:

• sortBy — name, createdDate, lastModifiedDate, notBefore, or expires
• sortDirection — ASC or DESC (default: DESC)
• maxResults — 1 to 100 (default: 25)

Supported standards

| Standard | Purpose | |----------|---------| | RFC 9728 | OAuth Protected Resource Metadata | | RFC 8414 | Authorization Server Metadata | | CIMD | Client ID Metadata Documents | | RFC 7591 | Dynamic Client Registration | | RFC 8628 | Device Authorization Grant | | PKCE (S256) | Required for all authorization code flows |