Connect an AI Agent#

GearTrain runs a remote Model Context Protocol server, so an AI agent can work with your account directly instead of handing you code to paste. An agent you connect can read your jobs and runs, follow a run’s console while it is active, browse your file system, and change jobs and files within the scopes you approve. This page connects an agent to your account and explains what it can and cannot do.

Before You Start#

You need an agent that can add a remote MCP server and sign in through your browser. There is nothing to install and no API key to copy.

The connection uses the account you are signed in with, so the agent sees what you see.

If your agent cannot complete the connection, see If Your Agent Cannot Connect.

Connect Your Agent#

Use these values wherever your agent asks for a server:

Name:  GearTrain
URL:   https://app.geartrain.dev/mcp
  1. In your agent, add a remote MCP server with those values.
  2. Start the connection. Your browser opens the GearTrain sign-in page.
  3. Sign in, review the request, and click Allow.

The agent now has its own access token. It renews that token in the background, so you do not repeat these steps for every session. You are asked to approve again only when you connect a new agent or re-authorize this one.

Some agents are configured in a file rather than a form. Use your agent’s own instructions for the location and the field names, and give it the two values above.

What You Are Approving#

The approval page names the agent, shows the account you are signed in as, and lists what the request allows. Read it before you click Allow.

  • Application. The agent’s name.
  • Signed in as. The account that will be able to act. If this is not the account you expected, switch accounts before continuing.

The page lists the permissions the agent asked for, each with a short description. The agent decides what to request; you decide what it gets. Everything starts checked. Two shortcuts sit above the list: Read only clears every permission that changes something, and Allow all restores the full request.

Unchecking a permission hides the matching tools, so the agent cannot do it. To widen access later, revoke the app and connect it again.

Check the Connection#

Ask the agent to confirm what it can do. A good first request is:

Use get_me and tell me which scopes you have.

The answer lists the scopes the agent holds. If the call fails, the sign-in did not complete; reconnect the server and approve again.

What the Agent Can Do#

Within the scopes you approve, an agent can read and change your jobs, runs, and files, and read secret names. A permission you clear removes the matching tools, so the agent cannot use them at all.

Anything the agent deletes is gone for good, the same as deleting it in the interface. Ask it to show you what it will change before it changes it.

What Stays in the Web Interface#

Some values never pass through an agent, by design:

  • Secret values. An agent can see that a secret exists and when it changed. It cannot read the value, create one, or change one. Create and update secrets yourself under Secrets.
  • Webhook endpoints. An agent can rename one, or enable and disable it. Creating an endpoint and its signing secret stays in the interface, on the job’s Webhooks section.
  • Account settings. Password and one-time passcode stay in the interface. An agent can read your plan, but it cannot change it.

How Agents Talk to You#

Agents adjust their explanations to a setting on your account. Open Settings and find it in the AI Agents card:

  • Guided explains in plain language and handles the code for you.
  • Balanced explains the outcome and shows code when it helps.
  • Direct keeps it brief and technical.

The setting is announced to an agent when it connects, so a change applies the next time an agent connects. You can always ask the agent to explain more or less in the moment.

Change or Revoke Access#

Access is listed under Settings > Authorized Apps, together with the scopes you approved and when the agent last used them. Click Revoke to remove it. The agent’s next request fails immediately.

Changing or resetting your password revokes every connected agent, so you will approve them again afterward.

Limits#

  • Requests. Agent requests share the account’s API rate limit. When it is reached, calls fail until the window resets.
  • File reads. read_file returns 64 KiB by default and 1 MiB at most.
  • Console output. get_run returns the last 100 entries by default and 500 at most.
  • Lists. list_runs returns 20 items by default and 100 at most.
  • History. Runs and their console output are deleted after your log retention period. An agent cannot recover them afterward.

If Your Agent Cannot Connect#

We add support for agents as they appear. If yours fails during setup, email [email protected] with:

  • the agent’s name and version;
  • where it stopped: adding the server, the sign-in page, or the first request;
  • the error message it showed.

Never paste a token, a secret value, or your password into that email.

Next Steps#