Set up Embedded MCP

You need MindCloud Embedded, a server-side API key, and one MindCloud end user ID for each signed-in user of your app.

1. Enable the MCP server

Enable MindCloud Embedded for your organization. Then open Embedded in MindCloud and turn on Enable MCP server for AI agents. This switch applies to the organization.

Create a Full Access key in API Keys. Your server needs Full Access to create end users and issue connect links. Store the key as a server secret. A MindCloud key can reach your whole organization through REST, so never send it to a browser or model prompt.

2. Create and store an end user

Call POST /v1/users from your server for each signed-in user. Store the returned userId beside your own user ID. externalId is your own stable ID; it does not replace the MindCloud userId in the MCP URL.

curl -X POST https://connect.mindcloud.co/v1/users \
  -H "Authorization: Bearer $MINDCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"externalId":"user-123","name":"Jane Doe","email":"jane@example.com"}'

POST /v1/users creates a new record every time. Lock your user record during first creation, then reuse its stored MindCloud ID. Create another only after the MCP endpoint returns END_USER_NOT_FOUND and you check the stored ID and organization.

The response contains the ID to store:

{"success":true,"data":{"userId":"enduser_AbCd1234EfGh"}}

3. Connect your server-side MCP client

Use Streamable HTTP. Get endUserId from your server session, never from the browser, model, or tool input.

import { createMCPClient } from '@ai-sdk/mcp';

const client = await createMCPClient({
  transport: {
    type: 'http',
    url: `https://connect.mindcloud.co/v2/embedded/end-users/${endUserId}/mcp`,
    headers: { Authorization: `Bearer ${process.env.MINDCLOUD_API_KEY}` }
  },
  protocolVersionDiscovery: false
});

try {
  const tools = await client.tools();
  // Give these tools to your server-side agent for this signed-in user.
} finally {
  await client.close();
}

The example uses the Vercel AI SDK. Any MCP client that supports Streamable HTTP and bearer headers can connect. A hosted MCP connector receives the key; give it a separate key with the lowest access level it needs.

4. Check the connection

List tools with a real stored end user ID. A read-only key lists five tools. A Run Workflows key adds two. A Full Access key lists all eight.

curl -X POST "https://connect.mindcloud.co/v2/embedded/end-users/$END_USER_ID/mcp" \
  -H "Authorization: Bearer $MINDCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Next, call list-connections. If the user needs an app, call get-connect-url and show that link only to the same user.