# Connect an AI agent with MCP

Glomo runs a remote [MCP](https://modelcontextprotocol.io) server that gives your AI coding agent the Glomo docs and API as tools. Without a credential, the agent can search the docs, find the right endpoint, read its schema, generate a sample request and get the ordered calls for an integration. With an MCP credential it can also call the API for you. Every call it makes, read or write, runs against your test (sandbox) account only.

## Server URL and authentication

| Setting | Value |
|  --- | --- |
| URL | `https://mcp.glomo.one/mcp` |
| Transport | Streamable HTTP (stateless, `POST` only) |
| Auth | `Authorization: Bearer <MCP credential>` |


- The credential is optional. Connecting, listing tools and every discovery tool work without one.
- The credential is an **MCP credential**, not your secret key. You mint it with your test secret key; see [Get an MCP credential](#get-an-mcp-credential). The server refuses a secret key.
- Before it runs `glomo_api_read` or `glomo_api_write`, the server checks that the credential was issued by Glomo for MCP, has not expired, and belongs to a sandbox account. It holds no key of its own: it forwards your credential to the Glomo API, which checks it again on every call.


The file-based configs below read the credential from the `GLOMO_MCP_CREDENTIAL` environment variable or prompt for it, so no credential lands in a file you commit. The Claude Code plugin reads the variable too. `claude mcp add` and Lovable are the exceptions: they save the value in their own settings, as their sections explain. Set it in the shell you start your client from:

```bash
export GLOMO_MCP_CREDENTIAL="<your MCP credential>"
```

## Get an MCP credential

Mint the credential with your **test secret key** over the Glomo API. If Glomo has turned on MCP credentials for your account, you can also generate it in the Merchant Dashboard under **API keys**, in test mode. See [Getting your Secret Key](/platform/authentication#getting-your-secret-key-on-first-login) for the key.

### Create

```bash
curl -X POST 'https://api.glomopay.com/api/v1/mcp-credentials' \
  -H "Authorization: Bearer $GLOMO_SECRET_KEY"
```

The request has no body. The response is `201 Created`:

```json
{
  "mcp_credential": "eyJhbGciOiJSUzI1NiJ9.example-payload.example-signature",
  "expires_at": "2026-10-28T06:30:00Z"
}
```

- `GLOMO_SECRET_KEY` in these calls is your test secret key. It is only used to mint or rotate the credential, and never goes into your agent's config.
- The API returns `mcp_credential` only in this response. Store it the way you store your secret key.
- It expires 30 days after it is minted. `expires_at` is in UTC.
- You can hold one active MCP credential at a time. If one is already active, create returns `409 Conflict` with `An active MCP credential already exists; rotate it instead`. Once it has expired, create works again.


### Rotate

```bash
curl -X POST 'https://api.glomopay.com/api/v1/mcp-credentials/rotate' \
  -H "Authorization: Bearer $GLOMO_SECRET_KEY"
```

The request has no body. The response is `200 OK`, in the same shape as create, with a new credential that is valid for 30 days.

- **The old credential stops working immediately.** There is no grace period, so update your client config before an agent next calls the API.
- If you have no active MCP credential, rotate returns `404 Not Found` with `No active MCP credential to rotate; create one instead`.


### Rules for both calls

- **Sandbox only.** Call them with your test secret key. With a live key they return `403 Forbidden` with `MCP credentials are only issued on sandbox`.
- **Only a secret key can mint or rotate.** With an MCP credential as the bearer they return `403 Forbidden` with `MCP credentials cannot manage MCP credentials`, so an agent cannot renew its own access.
- **Rate limit.** Create and rotate share a limit of 10 requests a minute per account. Beyond that you get `429 Too Many Requests` with `Too many MCP credential requests; try again in a minute`.
- A missing or invalid key returns `401 Unauthorized`.


## Tools

| Tool | Credential | What it does |
|  --- | --- | --- |
| `glomo_docs_search` | No | Searches these docs and returns cited excerpts with their URLs. |
| `glomo_api_search` | No | Finds an API operation by keyword. |
| `glomo_api_details` | No | Returns the parameters and request and response schemas for an `operationId`. |
| `glomo_sample_request` | No | Generates a cURL, Python or Node sample for your own app code. Samples read your secret key from `GLOMO_API_KEY`, not the agent's MCP credential. |
| `glomo_implementation_planner` | No | Returns the ordered API calls for an integration, copied from [Get started](/get-started). Given a goal, it lists the matching flows to choose from. |
| `glomo_api_read` | Yes | Runs a `GET` operation against your sandbox account. |
| `glomo_api_write` | Yes | Runs a `POST`, `PATCH` or `DELETE` operation against your sandbox account. |


The discovery tools cover the whole API. Only a reviewed allowlist of operations can be run; the rest come back marked `executable: false`, so the agent can read them but not call them. The planner never invents a call order: a goal with no authored flow says so.

## Set up your client

### Claude Code

#### Install the Glomo plugin

The plugin adds this MCP server and the Glomo [agent skills](/.well-known/skills/index.json) in one step. In Claude Code, run:

```text
/plugin marketplace add glomopay/glomo-ai-plugins
/plugin install glomo@glomo
```

- The plugin reads your credential from `GLOMO_MCP_CREDENTIAL` each time Claude Code starts, so it never saves the credential. Without the variable, the discovery tools still work.
- The skills are `/glomo:integration`, `/glomo:payins`, `/glomo:payouts`, `/glomo:testing` and `/glomo:webhooks`. Claude Code loads the right one when your task needs it, or you can run one by name.
- To offer the plugin to everyone who works in a repo, commit this to the repo's `.claude/settings.json`:

```json
{
  "extraKnownMarketplaces": {
    "glomo": { "source": { "source": "github", "repo": "glomopay/glomo-ai-plugins" } }
  },
  "enabledPlugins": { "glomo@glomo": true }
}
```


Check it with `/mcp` inside a session: `glomo` should be listed as connected.

#### Add the server only

To add the MCP server without the skills, run this once for all your projects:

```bash
claude mcp add --transport http --scope user glomo https://mcp.glomo.one/mcp \
  --header "Authorization: Bearer $GLOMO_MCP_CREDENTIAL"
```

Your shell expands `$GLOMO_MCP_CREDENTIAL` when you run this, so the credential is saved in `~/.claude.json`, which is private to you. To share the setup with your team without sharing a credential, commit a `.mcp.json` at the project root instead. Claude Code expands `${GLOMO_MCP_CREDENTIAL}` from each developer's environment at startup:

```json
{
  "mcpServers": {
    "glomo": {
      "type": "http",
      "url": "https://mcp.glomo.one/mcp",
      "headers": {
        "Authorization": "Bearer ${GLOMO_MCP_CREDENTIAL}"
      }
    }
  }
}
```

Check it with `claude mcp list`, or `/mcp` inside a session.

### Cursor

Add this to `~/.cursor/mcp.json` for all projects, or `.cursor/mcp.json` for one:

```json
{
  "mcpServers": {
    "glomo": {
      "url": "https://mcp.glomo.one/mcp",
      "headers": {
        "Authorization": "Bearer ${env:GLOMO_MCP_CREDENTIAL}"
      }
    }
  }
}
```

Cursor lists the server and its tools in its MCP settings once it connects.

### VS Code (GitHub Copilot agent mode)

Add this to `.vscode/mcp.json`. VS Code prompts for the credential the first time the server starts, so the file holds no secret:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "glomo-mcp-credential",
      "description": "Glomo MCP credential",
      "password": true
    }
  ],
  "servers": {
    "glomo": {
      "type": "http",
      "url": "https://mcp.glomo.one/mcp",
      "headers": {
        "Authorization": "Bearer ${input:glomo-mcp-credential}"
      }
    }
  }
}
```

Run **MCP: List Servers** from the Command Palette to check it started, then open Chat in agent mode and look for the Glomo tools in the tools picker.

### OpenAI Codex CLI

Codex connects to streamable HTTP servers directly; you do not need a bridge such as `mcp-remote`. You need a Codex CLI release that supports `bearer_token_env_var`. If your build rejects that key, upgrade Codex rather than putting the token inline. Add this to `~/.codex/config.toml`:

```toml
[mcp_servers.glomo]
url = "https://mcp.glomo.one/mcp"
bearer_token_env_var = "GLOMO_MCP_CREDENTIAL"
```

Codex sends the variable's value as `Authorization: Bearer <value>`. Check it with `codex mcp list`, or `/mcp` inside a session.

### Lovable

Lovable connects from its own servers, so it stores the credential itself rather than reading your environment. A custom MCP server is a personal chat connector: it is never part of your published app.

1. Open [Connectors](https://lovable.dev/dashboard?connectors), select **+** in the top right, and choose **MCP server**.
2. **Server name**: `glomo`.
3. **Connection type**, if shown: **Direct connection**.
4. **Server URL**: `https://mcp.glomo.one/mcp`.
5. **Authentication**: choose **Bearer token or API key** and paste your MCP credential. Do not leave the default **OAuth** selected; this server does not use OAuth. For docs and API discovery only, choose **No authentication**.
6. Select **Add server**.


## Check the connection

Ask your agent:

1. "List the Glomo MCP tools." You should see the seven `glomo_*` tools above.
2. "Use `glomo_docs_search` to find how to create a payout." You should get excerpts with `docs.glomo.one` links. This works without a credential.
3. With a credential set: "Use `glomo_api_read` to run `getBalance`." You should get your sandbox account's balances.


## Sandbox only

- **Reads and writes both run only against sandbox.** `glomo_api_read` and `glomo_api_write` refuse any credential that is not a sandbox credential, before the call reaches the Glomo API. An agent cannot read or change live data through this server.
- **Your secret key does not work here,** test or live. The server accepts only an MCP credential.
- **The credential lasts 30 days.** Rotate it before then, or create a new one after it expires, and update your client config.
- Keep the credential out of prompts, commits and shared config. Every setup above keeps it in your environment, an input prompt or the client's own store.


## Troubleshooting

**`Unauthorized: no Glomo credential supplied for this request.`**
The server received no credential. The header must be exactly `Authorization: Bearer <MCP credential>`. Check `echo $GLOMO_MCP_CREDENTIAL` in the shell you start the client from, and restart the client after setting it. A client started before you exported the variable does not see it.

**`Unauthorized: invalid credential.`**
The server rejected the credential before calling the API. It is your secret key rather than an MCP credential, the MCP credential has expired, or it was not issued by Glomo for MCP (for example, it was altered). [Create one](#create), or [rotate](#rotate) if it is still active, and update your config.

**A tool result with `"statusCode": 401`**
The Glomo API rejected the credential. Most often it was rotated, which ends the old one at once. Put the current MCP credential in your config.

**The client reports a 401 or an auth failure when connecting**
Not your credential: the server accepts every connection and only checks credentials on `glomo_api_read` and `glomo_api_write`. Check the URL ends in `/mcp`. In Lovable, make sure **OAuth** is not selected.

**`the execution tools are sandbox-only and require a sandbox credential`**
The credential is not a sandbox credential. Mint one with your test secret key.

**`Invalid arguments for tool glomo_api_read` (or `glomo_api_write`) with `Invalid enum value`**
Each tool accepts only the operations it can run. Either the operation is documentation only (`executable: false` in `glomo_api_search` or `glomo_api_details`), or you called it through the wrong tool: the `tool` field in those results names the right one. For a documentation-only operation, call the API from your own code; `glomo_sample_request` gives you the request.

**The Glomo tools do not show up**

- The URL must end in `/mcp`. Opening it in a browser returns `405 Method not allowed`: that is expected, because the server only accepts `POST`, and it proves the URL is reachable.
- Claude Code needs `--transport http` (without it, `claude mcp add` expects a local command). VS Code needs `"type": "http"`.
- Restart or reload the client after editing its config, then run its check command above.


## Related

- [llms.txt](https://docs.glomo.one/llms.txt) and [llms-full.txt](/llms-full.txt): these docs as plain text for agents.
- [Agent skills](/.well-known/skills/index.json): the catalogue of Glomo skills for your agent.
- [Get started](/get-started): the ordered calls that `glomo_implementation_planner` returns.
- [API reference](/api-reference/openapi), and the full contract as one document at [/openapi.yaml](/openapi.yaml).
- [Authentication](/platform/authentication): API keys, test and live environments, rotation.