# Studio API

Source: https://www.geardex.app/api-docs/studio-api

API access requires the GearDex Studio plan and a scoped Studio API key.

Send Studio API requests from your own code, or see how the MCP adapter sends them.

## API or MCP

Use direct HTTP calls when you control the client, for example your own script, server or agent framework. Use the [MCP adapter](https://www.geardex.app/api-docs/mcp-adapter) when an MCP host, for example Claude or Gemini, must use GearDex tools.

The two methods use the same Studio API key, scopes, audit log and webhooks. You can start with one method and add the other later.

Base URL

`https://www.geardex.app/api/studio-agent/v1`

## Build a client

1. Create a Studio API key.
2. Give the key only the [scopes](https://www.geardex.app/api-docs/scopes) that your client needs.
3. Send the key as a bearer token in each request. See [Authentication](https://www.geardex.app/api-docs/authentication).
4. Send requests to the [endpoints](https://www.geardex.app/api-docs/endpoints). Or, generate a client from the [OpenAPI document](https://www.geardex.app/api/studio-agent/openapi). See the [OpenAPI guide](https://www.geardex.app/api-docs/openapi).
5. Use backoff when you send a failed request again. See [Responses and errors](https://www.geardex.app/api-docs/errors) and [Rate limits](https://www.geardex.app/api-docs/rate-limits).

## How MCP calls the API

1. The host calls an MCP tool, for example `list_shoots`.
2. The adapter finds the Studio API endpoint for that tool.
3. The adapter sends a request with your key as a bearer token.
4. The Studio API checks the scopes and the record owner, and writes an audit log entry.
5. The adapter returns the JSON response to the host as the tool result.

The [tool map](https://www.geardex.app/api-docs/mcp-adapter#tools) shows each tool and the endpoint that it calls.

## Adapter behavior

**MCP adapter behavior**

| Aspect | Kind | Behavior |
| --- | --- | --- |
| `Auth` | behavior | The adapter sends GEARDEX\_STUDIO\_API\_KEY as a bearer token on each request. |
| `Timeout` | behavior | Each API call has a 20 second limit, which includes redirects and the response. The maximum response size is 2 MiB. |
| `Redirect handling` | behavior | The adapter follows a maximum of three redirects in the API path. It sends the key only to the same origin or to HTTPS GearDex addresses. A redirect for a write must keep the HTTP method. |
| `State` | behavior | The adapter keeps no credentials and no sessions. |
| `Write access` | behavior | Write tools use the same write scopes, audit log and webhooks as direct HTTP calls. |