AI Assistant (MCP Server)

Runner exposes itself as an MCP server, so an AI assistant can create and manage your projects, environments, schedules, and runs from a plain description of what you want. MCP (Model Context Protocol) is an open standard for connecting AI assistants to external tools and data; connecting Runner this way gives the assistant the same capabilities as the web UI, scoped to what your account can access.

Because the assistant can call the same operations the UI uses, a single prompt can chain several steps: provision an environment, set up a schedule, and write the shell command it runs.

Connecting an assistant

Open Integrations from the left sidebar (or search for it) and find the Connect an AI Assistant card. It shows your Runner instance’s MCP address:

https://<your-runner>/mcp

Add this address in your assistant’s connector or integration settings. For the clients Runner knows, the Add to … dropdown next to the address opens the client’s own screen for adding a connector:

• Claude — opens claude.ai’s connector settings in a new tab, with the address filled in.
• ChatGPT — opens ChatGPT’s plugin settings in a new tab; paste the address there.
• Cursor, VS Code, LM Studio — opens the app, if installed, with the address filled in.

For any other MCP-compatible client, copy the address with the button next to it and paste it into that client’s connector settings.

The first time an assistant connects, Runner shows the same consent screen used for any connected application. Approve it to let the assistant act on your behalf. The connection then appears in your Connected Applications list, where you can review or revoke it at any time.

See Connecting an AI Assistant for a full walkthrough, from adding the connector to your first prompts.

Self-hosted Runner without internet access

Whether this works depends on where the assistant’s connector settings actually run:

• claude.ai, ChatGPT, and the custom connector screen in Claude Desktop connect from the provider’s cloud: when you add a connector, their infrastructure calls your Runner instance’s address directly. This only works if that address is reachable from the public internet over HTTPS. A Runner instance behind a VPN or firewall, or otherwise internal-only, can’t be reached this way, however it’s configured.
• Locally-run clients (Claude Code, Cursor, VS Code, and LM Studio) run as a process on your own machine, so they can reach an internal-only Runner instance the same way your browser does.

TIP

If your Runner instance isn’t reachable from the internet, connect with a locally-run client instead. To use Claude Desktop, add Runner to its claude_desktop_config.json through mcp-remote, which runs on your machine and connects from your network instead of the provider’s cloud.

What you can do

Once connected, the assistant can read and write anything a Full Access connection is scoped to — the same access a personal access token has: project-level resources, plus a handful of account-wide reads such as your own account details, other users’ basic info, and instance-wide search and statistics. It can never modify your profile or account credentials, or create or revoke tokens on your behalf. If you only want the assistant to look things up, approve it with Read Only access instead.

Looking things up

• “List my Runner projects.”
• “Show me the schedules in my [project name] project.”
• “Any failed runs recently? Show me the last few for [project name] and pull up the log for the most recent failure.”
• “Which of my schedules are currently disabled?”
• “How has the nightly-backup schedule been doing over the last month?”
• “Search for anything related to ‘nightly backup’ — schedules, files, runs, whatever matches.”
• “What’s my Runner account email, and what role do I have?”

Building things

With Full Access, the assistant can create environments and schedules from a plain-language description. A Docker schedule’s Command field accepts a full multi-line script, so the assistant typically writes the whole job as one inline command against a plain base image like python:3.12-slim or node:20-slim: first installing the packages it needs, then the actual logic. For example:

• “Set up a new Docker environment in [project name] using the python:3.12-slim image, then create a schedule that runs it every night at 2am and dumps our database with pg_dump, uploading the result to S3.”
• “Build a schedule that scrapes [some URL] every hour with a Python script using requests and beautifulsoup4, and emails me if the page content changed.”
• “I need a Node.js job that pulls the latest exchange rates from an API and writes them to a CSV file. Set up the environment, install what it needs, and schedule it for 6am on weekdays.”
• “My nightly-backup schedule keeps failing — look at the last failed run’s log, figure out what’s wrong, and fix it.”

The same works for a job in bash, Python, Node.js, or anything else that runs in a container. See Building a Schedule From a Prompt for a full example, and Debugging a Failed Run with an AI Assistant for using it to fix one that broke.

Revoking access

An AI assistant connects the same way any other connected application does. Revoke it from the Connected Applications card on the Integrations page — revocation takes effect immediately.