> ## Documentation Index
> Fetch the complete documentation index at: https://docs.letsflow.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Hosted MCP

> Connect MCP-compatible assistants to Flow.

Flow exposes a **hosted MCP** server so external assistants can call curated tools against your organization's data. The endpoint uses **Streamable HTTP** at a single URL on the Flow deployment.

## Endpoint

| Item | Value |
| - | - |
| Server URL | `https://app.letsflow.ai/mcp` |
| Protocol | MCP over Streamable HTTP |
| OAuth metadata | `https://app.letsflow.ai/.well-known/oauth-authorization-server` |

Copy the server URL from **Settings → API & MCP Access** in the browser app.

## Connect an MCP client

<Steps>
  <Step title="Open API and MCP Access.">
    Sign in at [https://app.letsflow.ai](https://app.letsflow.ai). Go to **Settings → API & MCP Access**.
  </Step>

  <Step title="Copy the server URL.">
    Use `https://app.letsflow.ai/mcp` (or copy from the **Model Context Protocol (MCP) Server** card).
  </Step>

  <Step title="Add the server in your client.">
    Supported clients include **Claude Code**, **Cursor**, and **Continue**. Add a remote MCP server
    with the URL above.
  </Step>

  <Step title="Authenticate with OAuth.">
    Complete the OAuth flow when the client prompts you. If you belong to more than one
    organization, choose one during sign-in. Flow scopes the MCP session from that
    selection in the Connect access token. Clients such as Cursor, Claude, and Codex do not
    need a custom organization header.
  </Step>

  <Step title="Verify tools load.">
    The client should list Flow tools your principal is allowed to use. Tool visibility follows your
    org role and capabilities.
  </Step>
</Steps>

## How MCP fits with other surfaces

| Surface | Best for |
| - | - |
| **Browser** | Team members using Home, Conversations, and admin settings |
| **Hosted MCP** | Agent clients that need customer identity, request, catalog, and approval tools |
| **REST API** | Integrations, SDKs, and the Flow command-line interface (CLI) |
| **CLI** | Terminal scripts and automations |

MCP exposes a small customer contract over Flow requests and approvals rather than mirroring internal API resources.

## Authentication

| Method | Use on MCP |
| - | - |
| **OAuth** (from the client) | Supported for hosted MCP |
| **API keys** | Use with the [REST API](/api-reference) and [CLI](/setup/cli), not as the MCP bearer token |

Create service accounts and API keys on the same **API & MCP Access** page when you need machine access outside MCP.

## What clients can do

Published MCP tools cover requester work and automation authoring or operation, subject to the signed-in user's authorization.

Requester tools:

* `get_current_user`: confirm identity, teams, and active request or approval keys
* `search_requests`: find requests or retrieve one by its public request key
* `list_approvals`: list actionable approvals and open the exact approval in Flow
* `list_request_catalog`: list every available request option and its input schema
* `submit_request`: submit a matching published request option or a general request

Automation tools use the same authoring contracts as Flow's Automations area:

* List and retrieve authoring skills, approval procedures, integrations, action declarations, lint rules, connector health, automations, and runs.
* Lint complete automation TypeScript without saving it.
* Create a draft, save draft revisions and numbered versions, and run mocked validation review.
* Publish a saved version after Review and publication prerequisites pass.
* Start simulated or live runs asynchronously, inspect their state and safe logs, and request cancellation.

Unauthorized tools are omitted from the advertised list. Automation access follows the same team roles and permissions as the Flow app. Approval decisions always require explicit human action in the authenticated browser; MCP cannot perform them.

Automation creation, successful draft and version saves, publication, and automation lists return an absolute `automation_url`. You can use this link to view the automation in Flow. Your existing permissions determine what you can view and publish.

Save draft, Save version, Review, and Publish have separate outcomes:

* **Save draft** preserves source revisions while you edit.
* **Save version** records a numbered checkpoint, such as **v1**, using the same rules as **Save** in Flow.
* **Review** checks validation scenarios and required coverage for the exact saved revision.
* **Publish** makes a saved version available to your authorized audience after its prerequisites pass.

Both save operations preserve work. Saving a version does not run Review or publish it. You can keep unfinished work as a draft or save completed edits as a version. An ordinary edit does not require publication.

Draft revision numbers and numbered versions differ. For example, saving revision 2 as a version without editing can make it **v1**. MCP publication still uses revision 2.

To create and publish an automation through MCP:

1. Create a draft with `create_automation`.
2. Save your draft source, input examples, and validation scenarios with `save_automation_revision`.
3. Save a version with `save_automation_version`, using the automation key and draft revision.
4. Run validation scenarios for the returned revision with `run_automation_validation_scenarios`.
5. Confirm that scenarios and coverage pass with `list_automation_validation_scenarios`.
6. Call `publish_automation` with that revision and your authorized audience.

Saving a version returns `status: "saved"`, `revision`, and `version_number`. Success confirms a saved checkpoint. Check Review results and publication state separately. Repeated saves of the same draft reuse its version. If updated connection contracts create a newer revision, validate the returned revision before publishing.

If publication returns `setup_required` with `reason_code: "automation_version_not_saved"` and `next_step: "save_automation_version"`, call that tool and validate the returned revision. Retry publication with a new mutation key. Replaying a completed setup mutation returns its original receipt, including after saving a version.

You can complete this authoring path through MCP. Browser links provide optional navigation to the current automation. Opening a link does not save, publish, select a historic revision, or restore your requested audience.

## MCP access mode

Organization administrators set **MCP access mode** on the **Model Context Protocol (MCP) Server** card in **Settings → API & MCP Access**. The mode controls what every MCP connection in the organization can do.

| Mode | Effect |
| - | - |
| **Read and write** (default) | Connections can search and read, submit requests, create and publish automations, and run them |
| **Read only** | Connections can search, read, and list. They cannot make changes. Write tools are hidden for every connection |

The mode is a ceiling, not a grant. It never lets a connection do more than that person can already do in Flow. Approval decisions stay in the authenticated browser. MCP cannot perform them.

A change applies to new MCP requests immediately. Flow records the change in the audit trail.

## Troubleshoot connection issues

<Steps>
  <Step title="Confirm the server URL.">
    Confirm the server URL ends with `/mcp` and uses `https://app.letsflow.ai`.
  </Step>

  <Step title="Retry OAuth.">
    Retry OAuth if the client cached an expired token. Multi-organization users should complete
    organization selection during that flow.
  </Step>

  <Step title="Check multi-organization linking.">
    If the client reports that your identity is linked in multiple organizations, disconnect and
    reconnect so organization selection can be recorded on the new token.
  </Step>

  <Step title="Verify capabilities.">
    Verify your user has the capabilities required for the tools you expect (team admin or org
    admin may need to grant access).
  </Step>

  <Step title="Check MCP access mode.">
    If write tools are missing for everyone, check the [MCP access mode](#mcp-access-mode); an org
    admin may have set it to read only.
  </Step>

  <Step title="Compare across surfaces.">
    Compare behavior with the same action in the browser or [command-line interface (CLI)](/setup/cli)
    to isolate client vs permission issues.
  </Step>
</Steps>

## Legal pages for directory listings

When an assistant directory or marketplace asks for Flow legal URLs, use:

| Page | URL |
| - | - |
| Privacy Policy | `https://app.letsflow.ai/privacy` |
| Terms | `https://app.letsflow.ai/terms` |

The privacy URL redirects to ServiceNow's published privacy policy. Hosted MCP tools also advertise directory-safe titles and annotation hints (`readOnlyHint`, `destructiveHint`, `openWorldHint`) on `tools/list`.

## Related topics

* [CLI](/setup/cli)
* [API Reference](/api-reference)
* [Day 1 setup](/setup/day-1-setup)
* [Authentication](/setup/authentication)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.