Connect AI Agents with OSC

The integration of Model Context Protocol (MCP) into Eyevinn Open Source Cloud (OSC) now enables anyone – regardless of technical expertise – to deploy and manage sophisticated web services simply by describing their needs in plain language.

In this guide we describe how you enable this in your favorite AI agent.

Want OSC to run your agent tasks automatically? Check out My Agent Tasks to schedule Claude Code tasks that run in the cloud on your behalf — no local machine required.

For Claude Desktop Users

Configure and extend your Claude for Desktop so that it can get access to all the tools provided by Open Source Cloud. Don't worry it will ask for your permissions before executing any actions.

Step 1: Download Claude for Desktop

Start by downloading Claude for Desktop, choosing either macOS or Windows.

Follow the installation instructions.

If you already have Claude for Desktop, make sure it's on the latest version by clicking on the Claude menu on your computer and selecting "Check for Updates…"

Step 2: Connect Claude with OSC

Open up the Claude menu on your computer and select "Settings...".

Select the menu alternative on the left labelled "Connectors".

In the bottom of the list you find a button "Add custom connector"

Click on it and give the connector a name, for example "OSC" and enter the URL https://mcp.osaas.io/mcp.

Then press Add.

Go to the connector and press the button "Connect". You are now prompted to authenticate with Open Source Cloud and allow access for Claude to access your OSC account on your behalf. Press the button "Allow" to allow this.

Step 3: Try it out!

You can now talk to Claude to help you perform various tasks and it will complete the tasks using all the open source tools that Eyevinn Open Source Cloud are making available.

Here are some things you might try to ask Claude:

• Can you help me setup a stream for live streaming?
• Can you create English subtitles in VTT format for my video file?
• Can you take my video file and turn it into a black and white movie?
• Can you create a workspace mailbox for me? (Professional/Business plans only)
• Can you check the status of my workspace email?
• What is the status of my eyevinn-test-adserver instance?
• Restart my eyevinn-subtitle-generator instance called mysubs
• Pause my eyevinn-test-adserver instance called myadserver (or: suspend, stop, shut down, turn off, disable — all treated as a reversible pause)
• Update the configuration of my eyevinn-test-adserver instance called myadserver (changes are merged with the existing config; unspecified settings are preserved)
• Estimate the cost of running eyevinn-test-adserver before I deploy it
• Create a service token for eyevinn-test-adserver so I can call its API
• Create a delegate token for my service instance so I can share temporary access with a colleague
• Set the IP allowlist on my eyevinn-test-adserver instance called myadserver to 203.0.113.0/24 (restrict access to a specific network)
• Clear the IP allowlist on my myadserver instance so it is reachable from any IP
• What service categories are available on OSC?
• List all services in the database category
• What OSC tools and capabilities are available? (uses list-osc-capabilities)
• What's my current token usage and which services are consuming the most?
• How long will my tokens last at my current usage rate?
• Upgrade my plan to Professional
• Create a personal access token called "ci-pipeline" for CI use, valid for 30 days
• List all my personal access tokens
• Revoke my personal access token with ID pat-abc123
• Wait for my myadserver instance to become ready (uses wait-for-service-ready — the agent calls this automatically after creating an instance, polling every 10 seconds until it reports healthy or times out after 5 minutes)
• Which workspace am I connected to right now? (uses refresh-workspace — re-reads which workspace your current token maps to; useful if the agent appears to be managing the wrong workspace after you reconnect or switch sub-workspaces)

When you ask about your plan or token usage, the AI agent provides a per-service breakdown showing which services consume the most tokens, your consumption trend, and an estimate of how long your balance will last. If you ask to upgrade your plan, the agent can generate a direct Stripe Checkout link — useful when working in a terminal-based agent like Claude Code.

Managing Personal Access Tokens via AI Agent

You can create, list, and revoke Personal Access Tokens (PATs) directly from your AI agent. This is useful for provisioning automation credentials without opening the web console.

Create a PAT for a CI pipeline:

"Create a personal access token named 'ci-deploy' with purpose 'github-actions', expiring in 30 days"

The agent returns the token value and its metadata. The raw token is shown only once — copy it immediately and store it in your secrets manager.

The expiry is capped at the remaining lifetime of the PAT you used to authenticate the MCP session, so you cannot mint tokens that outlive your own.

List existing tokens:

"List all my personal access tokens"

Revoke a token:

"Revoke my personal access token with ID pat-abc123"

Waiting for Service Instances to Start

After creating a service instance, the agent automatically calls wait-for-service-ready to poll the instance until it reports healthy. You do not need to ask for this explicitly — the agent handles it after every create-service-instance call.

The tool polls every 10 seconds and returns as soon as the instance is running (up to a maximum of 5 minutes). If the instance fails to start within that window, the agent tells you and suggests checking the logs.

If you ever want to wait for an existing instance that is already starting, you can ask directly:

"Wait for my myadserver instance to be ready"

Reconnecting and Switching Workspaces

If you reconnect the OSC MCP connector or switch to a different sub-workspace while Claude is running, subsequent tool calls may still target your previous workspace. To force Claude to re-read which workspace the current token maps to, ask:

"Which workspace am I connected to right now?"

The agent calls refresh-workspace, which returns the workspace ID decoded live from your current authentication token along with a timestamp confirming this is a fresh read (not a cached value). If the returned workspace ID differs from what you expected, update your MCP connector with the correct token and ask again to confirm the switch.

Discovering All Capabilities

The default MCP connection exposes a curated set of essential tools. To discover the full capability surface, ask the agent to run list-osc-capabilities. It returns all available tool categories and workflow skills (prompts).

You can also scope which MCP tools are exposed by appending ?filter=<category> to your MCP server URL. This keeps the tool list focused on a single domain — useful for agents that only need a subset of OSC capabilities.

Filter	Tools exposed
instances	Service instance management (create, delete, describe, restart, backup, suspend)
apps	My Apps deployment, Agentic SDLC, Git credentials
databases	Database creation and management
storage	Object storage buckets
domains	Custom domain mappings
mailboxes	Email and mailbox tools
analytics	Analytics setup
billing	Plan, subscription, and cost tools
admin	Tokens, audit logs, cache, feedback admin, consent
agent-tasks	Agent task CRUD

For example, to expose only database tools, configure your MCP client with https://mcp.osaas.io/mcp?filter=databases.

MCP URL Modes

In addition to category filters, the OSC MCP server supports two special modes you can activate with ?mode= in the URL.

Mode	URL parameter	Description
Read-only	?mode=readonly	Exposes only tools that do not modify state (list, describe, get). Useful for monitoring and audit agents that should never create or delete resources.
Operator	?mode=operator	Exposes only two meta-tools for marketplace embedding: osc_search_tools and osc_call_tool. Use this when building a product that embeds OSC into its own AI assistant.

For example: https://mcp.osaas.io/mcp?mode=readonly

Embedding OSC in Your Own AI Product (Operator Mode)

If you are building a product with an embedded AI assistant and want to give it access to OSC capabilities without exposing the full tool surface, use operator mode. Your assistant gets two tools:

• osc_search_tools — returns a lightweight catalog of OSC tool names and descriptions (no schemas). Use this to let your assistant discover which OSC operation to call next. Optionally filter by category or a free-text query.
• osc_call_tool — dispatches a call to any OSC tool by name, passing the required arguments. The tool executes with normal user-scoped permissions.

This two-tool surface keeps your assistant's context window lean and avoids exposing the full OSC schema to an external AI client.

Configure your embedded assistant with:

https://mcp.osaas.io/mcp?mode=operator

Your users still authenticate with their own OSC account — operator mode affects which tools are visible, not who the actions run as.

When you ask the agent to estimate the cost of a service before deploying it, the agent checks your current token balance, daily refill rate, and burn rate to project how many days your balance will last after adding the new service. It will suggest upgrading your plan if you are running low.

You can also estimate the cost of a full stack of services in one go by listing them together:

"Estimate the total cost of running a PostgreSQL database, a Ghost blog, and a Plausible Analytics instance"

The agent calls estimate-service-cost with a services array and returns a single aggregate verdict with a per-service breakdown table showing the daily token cost and projected runway for the combined stack.

As needed, Claude will call the relevant tools and seek your approval before taking an action.

For Claude Code Users

Visit Settings → MCP in the OSC web console and copy the connection command from there. The command includes your personal MCP URL with authentication pre-configured. Paste and run it in your terminal, then start Claude Code:

% claude

Claude Code is now connected to OSC and ready to use.

Build a Full-Stack App with Claude Code and OSC

Want to see a complete example? The Build & Deploy a Full-Stack App with Claude Code tutorial walks through a 5-step workflow — from project setup to a live production deployment — using Claude Code with the OSC MCP integration.

Manage Services from a Service Page

When you have active instances of a service, an "Manage with AI Agent" chip appears on the service's dashboard page. Clicking it opens the AI Agent panel with a pre-filled prompt to list your instances of that service — a quick way to jump into AI-assisted management.

Spawning Subagents with OSC MCP Access

When Claude Code spawns a subagent using the Agent tool, the subagent does not inherit the parent session's MCP connections. If your subagent needs to call OSC tools, you must pass the MCP configuration to it explicitly.

The get-mcp-config OSC tool returns a ready-to-paste .claude/settings.json block with your credentials pre-filled:

1. Ask Claude Code: "Give me the OSC MCP config for a subagent" (or call get-mcp-config directly)
2. Claude returns a JSON snippet with your token embedded
3. Write the snippet to .claude/settings.json in the subagent's working directory before spawning it, or paste the block directly into the subagent's prompt so it can write the file itself

The returned configuration looks like this:

{
  "mcpServers": {
    "osc": {
      "type": "http",
      "url": "https://mcp.osaas.io/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

This is especially useful when you use My Agent Tasks to run orchestrator tasks that spawn their own specialist subagents — each subagent needs this configuration to call OSC tools independently.

Troubleshooting

If the command above does not work, you can configure the connection manually by editing your Claude configuration file ~/.claude.json. Replace <personal-access-token> with the token from Settings/API:

"mcpServers": {
  "osc": {
    "type": "http",
    "url": "https://mcp.osaas.io/mcp",
    "headers": {
      "Authorization": "Bearer <personal-access-token>"
  }
},

For VS Code Users

Click on View and Command Palette menu item.

Start typing "MCP" and choose Add server.

Choose HTTP.

Enter the following URL: https://mcp.osaas.io/mcp

Give it a name, for example "Open Source Cloud".

Choose whether it should be globally available or only the current workspace. Then choose Allow when asked for allowing authentication.

Authenticate in Open Source Cloud and give VS Code access to your account. Once authenticated you should have the tools available for your agent.

Alternative: Bearer token via .vscode/mcp.json

If the OAuth flow does not work or you prefer direct token authentication, you can use a project-level configuration file instead.

1. Get your Bearer token from Settings → API in the OSC web console.
2. Create .vscode/mcp.json in your project root and add:

{
  "servers": {
    "osc": {
      "type": "http",
      "url": "https://mcp.osaas.io/mcp",
      "headers": { "Authorization": "Bearer <your-token>" }
    }
  }
}

Replace <your-token> with your actual token. Do not commit this file to version control — it contains your personal access token.

For Cursor Users

Cursor supports MCP through a configuration file.

Step 1: Create or Edit the MCP Configuration File

Create or edit the file at ~/.cursor/mcp.json with the following content:

{
  "mcpServers": {
    "osc": {
      "type": "http",
      "url": "https://mcp.osaas.io/mcp"
    }
  }
}

Step 2: Restart Cursor

Close and reopen Cursor for the configuration to take effect.

Step 3: Authenticate

When you first interact with your AI agent in Cursor, it will prompt you to authenticate with OSC. Click the authentication link and grant access.

Troubleshooting

If authentication via browser doesn't work, you can use your personal access token:

1. Navigate to Settings/API in the OSC web console
2. Copy your personal access token
3. Update ~/.cursor/mcp.json:

{
  "mcpServers": {
    "osc": {
      "type": "http",
      "url": "https://mcp.osaas.io/mcp",
      "headers": {
        "Authorization": "Bearer <your-personal-access-token>"
      }
    }
  }
}

Replace <your-personal-access-token> with your actual token.

For Windsurf Users

Windsurf supports MCP through a JSON configuration file.

Step 1: Create or Edit the MCP Configuration File

Create or edit the file at ~/.codeium/windsurf/mcp_config.json with the following content:

{
  "mcpServers": {
    "osc": {
      "serverUrl": "https://mcp.osaas.io/mcp",
      "headers": {
        "Authorization": "Bearer <your-personal-access-token>"
      }
    }
  }
}

Replace <your-personal-access-token> with the token from Settings/API in the OSC web console.

Step 2: Restart Windsurf

Close and reopen Windsurf for the configuration to take effect.

For Codex CLI Users

OpenAI Codex CLI supports MCP with a built-in OAuth flow.

Step 1: Register the OSC MCP Server

Run the following commands in your terminal:

codex mcp add osc --url https://mcp.osaas.io/mcp
codex mcp login osc

The second command opens a browser window for OAuth — sign in with your OSC account and grant access.

Step 2: Use Codex with OSC

Codex now has access to OSC tools in every session. Start a chat and try: "list available services on OSC".

Troubleshooting

If your Codex version does not support the mcp add command, you can fall back to the manual TOML configuration. Create or edit ~/.codex/config.toml:

# ~/.codex/config.toml
[mcp_servers.osc]
url = "https://mcp.osaas.io/mcp"
bearer_token_env_var = "OSC_ACCESS_TOKEN"

Export your token first: export OSC_ACCESS_TOKEN=<your-personal-access-token>. Replace the placeholder with the token from Settings/API.

For ChatGPT Desktop Users

ChatGPT Desktop (macOS and Windows) supports custom MCP connectors.

1. Open ChatGPT Desktop and go to Settings.
2. Click Connectors in the left sidebar.
3. Click Add custom connector.
4. Set the type to Streamable HTTP, name it OSC, and paste https://mcp.osaas.io/mcp as the URL.
5. Save and return to chat. OSC tools are now available in your conversations.

For more information, see the OpenAI MCP documentation.

For Amazon Q CLI Users

Amazon Q CLI supports MCP servers through a JSON configuration file.

Step 1: Install Amazon Q CLI

brew install amazon-q

Step 2: Configure the MCP Server

Create or edit ~/.aws/amazonq/mcp.json and add:

{
  "mcpServers": {
    "osc": {
      "command": "npx",
      "args": ["-y", "@osaas/mcp-server"],
      "env": { "OSC_ACCESS_TOKEN": "<replace_with_your_personal_access_token>" }
    }
  }
}

Replace <replace_with_your_personal_access_token> with the token from Settings/API.

Step 3: Use Amazon Q with OSC

Start a chat session with q chat and try: "list services on OSC".

For more information, see the Amazon Q MCP documentation.

For JetBrains Users

JetBrains IDEs (IntelliJ, WebStorm, GoLand, and others) support MCP through the AI Assistant settings.

1. Open your JetBrains IDE and go to Settings > Tools > AI Assistant > Model Context Protocol.
2. Click the + button to add a new MCP server.
3. Set the type to Streamable HTTP, name it osc, and paste https://mcp.osaas.io/mcp as the URL.
4. Click OK and restart the AI assistant. OSC tools appear in the AI chat.

You can also add the server manually by editing ~/.config/JetBrains/mcp.json:

{
  "mcpServers": {
    "osc": {
      "url": "https://mcp.osaas.io/mcp",
      "transportType": "streamable-http"
    }
  }
}

For more information, see the JetBrains AI Assistant documentation.

For Cline Users

Cline is an autonomous coding agent extension for VS Code.

1. Install the Cline extension from the VS Code marketplace.
2. Open the Cline sidebar and click the MCP servers icon (grid icon) at the top.
3. Click Add MCP Server and choose Streamable HTTP.
4. Name it osc and paste https://mcp.osaas.io/mcp as the URL.
5. Save. Cline lists connected tools automatically in each new task.

For more information, see the Cline MCP documentation.

For Warp Users

Warp is an AI-native terminal that supports MCP agent actions.

1. Open Warp and click the AI icon in the toolbar to open Warp AI.
2. Go to Settings > AI > MCP Servers.
3. Click Add MCP Server.
4. Set transport to Streamable HTTP, name it osc, and paste https://mcp.osaas.io/mcp as the URL.
5. Save. Warp AI now has access to all OSC tools in agent sessions.

For more information, see the Warp MCP documentation.