# Connect your AI agent

> How to connect Claude, ChatGPT, GitHub Copilot, Cursor, Gemini or any other MCP client to the Tilopay MCP server.

- kind: guide
- status: stable
- last_verified: 2026-10-20
- url: https://tilopay.com/en/developers/agentes/mcp/conectar

Every agent connects to the same server through the same flow: you add a remote MCP server with
the Tilopay URL and authorize the session in the browser. The only thing that changes per agent is
where you add it.

```text
https://mcp.tilopay.com/mcp
```

The MCP server version in production is **0.3.0**.

## Before connecting [#antes]

1. There is no form and no prior approval: an active Tilopay account is enough.
2. During authorization you sign in with your Tilopay dashboard email and password and confirm the
   verification code Tilopay sends. The assistant user is created automatically at that moment and
   tied to your account.
3. Review [what an agent can do](/en/developers/agentes/mcp/permisos) before connecting it, especially
   the tools marked as sensitive.

> **Warning:** Never paste your `apiKey`, `apiUser` or `apiPassword` into the agent or its config file.
>   Merchant credentials live encrypted on the Tilopay server: the agent only handles its own OAuth
>   session.

## Claude [#claude]

Claude supports remote connectors, both in the desktop app and on the web.

1. Add a remote custom connector with the server URL.
2. Claude opens the Tilopay authorization screen: sign in with your Tilopay credentials and
   confirm the verification code.
3. Review the consent screen (requesting application, return URL and permissions) and approve.
4. Back in the conversation, the Tilopay tools are available.

There is no token to paste: the connector registers itself.

## ChatGPT [#chatgpt]

ChatGPT connects as a remote connector using the same URL.

1. Add the server as a remote connector with the URL above.
2. Authorization completes in the browser with your Tilopay credentials and the verification code.
3. Once approved, the connector is active and the model can call the tools.

## GitHub Copilot and VS Code [#copilot]

In VS Code (with Copilot in agent mode) you declare a remote HTTP MCP server.

1. Declare the server with the URL, no token or credentials in the config file.
2. On first use, the editor opens the browser to authorize.
3. After approving, the tools show up in the agent's tool list.

## Cursor and other editors [#cursor]

Cursor and equivalent editors use the same scheme: a remote MCP server over HTTP.

1. Add the remote server with the URL, no token in the configuration.
2. Authorize in the browser when the editor asks.
3. Enable the tools for the editor's chat or agent.

## Gemini [#gemini]

Gemini clients that support remote MCP connect the same way: register the server URL and authorize
in the browser. If the client only supports local stdio MCP servers, you need a bridge that speaks
Streamable HTTP against the Tilopay URL.

## Other MCP clients [#otros]

For a custom client or any other agent, the requirement is support for **Streamable HTTP**
transport and **OAuth 2.0 with dynamic client registration**. The sequence is:

1. The client calls the server and gets a `401` with `WWW-Authenticate`, pointing to
   `/.well-known/oauth-protected-resource`.
2. The client discovers the identity provider endpoints.
3. It registers dynamically and opens the authorization screen.
4. The user signs in and approves the consent screen.
5. The client stays connected with `authorization_code` and `refresh_token`.

The only thing you configure is the server URL.

## Verify the connection [#verificar]

Ask the agent to list the available tools: the Tilopay ones should appear, organized in the
14 groups of the [acquiring API](/en/developers/agentes/mcp/adquirencia) (full list). The
[banking API (BaaS)](/en/developers/agentes/mcp/api-bancario) group is enabled on request and only
works for users with Tilopay banking API credentials.

A safe first test is a read-only query, for example asking for transactions in a date range. For
full flows see the [recipes](/en/developers/agentes/mcp/recetas).

## Dates in UTC [#fechas-utc]

For sales queries, send `startDate` and `endDate` in UTC using
`YYYY-MM-DD HH:mm:ss`. Convert the local range before querying: Costa Rica is
UTC-6, so the local day 2026-10-20 runs from `2026-10-20 06:00:00` to
`2026-10-21 05:59:59` UTC. Use the same conversion when comparing periods.

## If something fails [#problemas]

- **The client never opens authorization**: check the server is declared as remote over HTTP, not
  as a local server.
- **Authorization never completes**: sign in with your Tilopay dashboard email and password, and
  confirm the verification code sent to your email.
- **The agent sees no tools**: several clients require enabling them for the conversation or for
  agent mode after connecting.
- **A tool returns empty**: it may be the queried environment; several tools default to
  `production`.