> ## Documentation Index
> Fetch the complete documentation index at: https://gtmapis.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP and Agent Tools

> Use GTMAPIs from coding agents and GTM workflow agents through hosted MCP or a local stdio server

GTMAPIs supports agent workflows as a developer-experience layer for API-first GTM infrastructure. The primary buyers are still outbound agencies and GTM engineers who need reliable validation workflows, predictable credit economics, and clear result semantics.

There are two MCP connection modes:

| Mode       | Transport                                            | Credential model                                                                                   | Best for                                                   |
| ---------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| Hosted MCP | Streamable HTTP at `https://www.gtmapis.com/api/mcp` | OAuth-style bearer tokens minted by GTMAPIs with PKCE, scopes, expiry, revocation, and audit rows. | Remote MCP clients and browser-mediated agent connections. |
| Local MCP  | Local stdio server from `@gtmapis/mcp`               | Restricted API key stored in the MCP client environment as `GTMAPIS_API_KEY`.                      | Users who want credentials to stay local.                  |

## Hosted MCP

Hosted MCP does **not** require users to paste unrestricted live API keys into remote agent clients. MCP clients connect to:

```text theme={null}
https://www.gtmapis.com/api/mcp
```

The hosted endpoint uses MCP Streamable HTTP and the MCP HTTP authorization flow:

| Endpoint                                  | Purpose                                               |
| ----------------------------------------- | ----------------------------------------------------- |
| `/.well-known/oauth-protected-resource`   | Protected-resource metadata for MCP clients.          |
| `/.well-known/oauth-authorization-server` | Authorization server metadata.                        |
| `/api/mcp/register`                       | Dynamic public client registration.                   |
| `/api/mcp/authorize`                      | Browser consent and PKCE authorization code issuance. |
| `/api/mcp/token`                          | Authorization-code and refresh-token exchange.        |
| `/api/mcp/revoke`                         | Token revocation.                                     |

Hosted MCP currently exposes the first safe tool slice:

| Tool                     | Purpose                                                                                                                                               | Required hosted scope   |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| `gtmapis_docs`           | Return canonical docs, public API URLs, hosted/local auth guidance, product availability, and integration rules.                                      | Any hosted MCP token    |
| `gtmapis_load_docs`      | Return the full GTMAPIs integration guide (`llms-full.txt`) as prose for agent onboarding.                                                            | Any hosted MCP token    |
| `gtmapis_get_credits`    | Read the Credit Ledger balance for the authenticated account.                                                                                         | `credits:read`          |
| `gtmapis_get_usage`      | Return a usage summary: credit consumption plus validation job stats.                                                                                 | `credits:read`          |
| `gtmapis_validate_email` | Validate one email through the Product Control Plane-owned validation execution path.                                                                 | `email:validate:single` |
| `gtmapis_create_api_key` | Mint a restricted API key for direct REST or local-MCP use. Granted scopes are clamped to the calling token's scopes and never include `keys:manage`. | `keys:manage`           |

Hosted tokens are audience-bound to `https://www.gtmapis.com/api/mcp`; they are not public API keys and are not forwarded to the public validation API.

## Local MCP

The local package runs as a stdio MCP server and calls the canonical public API with a restricted GTMAPIs API key from the local MCP client environment.

| Tool                                  | Purpose                                                                                             | API key required | Recommended scope       |
| ------------------------------------- | --------------------------------------------------------------------------------------------------- | ---------------- | ----------------------- |
| `gtmapis_docs`                        | Return canonical docs, public API URLs, auth guidance, product availability, and integration rules. | No               | None                    |
| `gtmapis_get_credits`                 | Read the credit balance for the account associated with the configured key.                         | Yes              | `credits:read`          |
| `gtmapis_validate_email`              | Validate one email through `POST /v1/validate`.                                                     | Yes              | `email:validate:single` |
| `gtmapis_validate_bulk`               | Validate up to 100 emails through `POST /v1/validate/bulk`.                                         | Yes              | `email:validate:bulk`   |
| `gtmapis_create_validation_job`       | Create an asynchronous validation job.                                                              | Yes              | `email:validate:bulk`   |
| `gtmapis_list_validation_jobs`        | List asynchronous validation jobs.                                                                  | Yes              | `email:validate:bulk`   |
| `gtmapis_get_validation_job`          | Get validation job status and summary.                                                              | Yes              | `email:validate:bulk`   |
| `gtmapis_get_validation_job_download` | Return a signed results CSV download URL handoff.                                                   | Yes              | `email:validate:bulk`   |

Product-backed tools are registered only when the public product catalog marks the product generally available and the tool declares a product-specific API key scope. Premium Catch-All Recovery is available in the public product catalog but should still be exposed only through recovery-specific scopes and tools. Social Intelligence, Ad Intelligence, Company Intelligence, Email Finder, People Data, and Prospecting remain future, privately gated, or dormant products until promoted in the public product catalog and docs navigation.

## Create a Scoped Local Agent Key

<Steps>
  <Step title="Open API Keys">
    Go to [Dashboard → API Keys](https://www.gtmapis.com/dashboard/api-keys).
  </Step>

  <Step title="Create a restricted key">
    Choose only the scopes the local agent needs. For credit lookup, select `credits:read`. For single validation, select `email:validate:single`. For bulk validation and async jobs, select `email:validate:bulk`.
  </Step>

  <Step title="Store it in the MCP client config">
    Put the key in the client environment as `GTMAPIS_API_KEY`. Do not paste unrestricted live keys into shared agent configs.
  </Step>
</Steps>

## Claude Desktop Local Setup

After the package is available in your package manager, add this server to your Claude Desktop MCP configuration:

```json theme={null}
{
  "mcpServers": {
    "gtmapis": {
      "command": "npx",
      "args": ["-y", "@gtmapis/mcp"],
      "env": {
        "GTMAPIS_API_KEY": "gtm_test_1234567890abcdef1234567890abcdef"
      }
    }
  }
}
```

For local development from a checkout of this repository, use an absolute path:

```json theme={null}
{
  "mcpServers": {
    "gtmapis-local": {
      "command": "node",
      "args": ["/absolute/path/to/gtmapis/mcp/bin/gtmapis-mcp.mjs"],
      "env": {
        "GTMAPIS_API_KEY": "gtm_test_1234567890abcdef1234567890abcdef"
      }
    }
  }
}
```

Restart Claude Desktop after editing the config.

## Generic Local MCP Client

Use stdio transport and launch the server as a local process:

```json theme={null}
{
  "command": "npx",
  "args": ["-y", "@gtmapis/mcp"],
  "env": {
    "GTMAPIS_API_KEY": "gtm_test_1234567890abcdef1234567890abcdef",
    "GTMAPIS_BASE_URL": "https://api.gtmapis.com"
  }
}
```

`GTMAPIS_BASE_URL` is optional. Leave it unset for production so tools call the canonical public API host.

## Example Agent Requests

Ask your MCP-enabled agent:

```text theme={null}
Use GTMAPIs docs to show me the canonical auth header, validation statuses, hosted MCP endpoint, and rate-limit guidance.
```

```text theme={null}
Validate john@company.com with GTMAPIs and explain whether it is high-value for B2B outbound.
```

```text theme={null}
Check my GTMAPIs credit balance before validating this list.
```

## Security Notes

* Hosted MCP uses bearer tokens issued for `https://www.gtmapis.com/api/mcp`; do not send public API keys as hosted MCP bearer tokens.
* Local MCP uses `X-API-Key` credentials through the MCP client environment, not browser code.
* Create a restricted key per local agent or automation.
* Revoke local API keys from the dashboard when an agent, contractor, or workflow no longer needs access.
* Use `/v1/validate/bulk` or `/v1/validate/batch` for multi-email public API workflows instead of asking an agent to fan out many single-email calls.
* Treat future or gated product names as roadmap context, not available public API surface.

## Related Docs

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/authentication">
    Create keys, understand scopes, and store credentials safely.
  </Card>

  <Card title="OpenAPI Spec" icon="file-code" href="/api-reference/openapi">
    Machine-readable public API reference for available-now endpoints.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Make your first validation request.
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/guides/rate-limits">
    Build agent workflows that respect retry and rate-limit headers.
  </Card>
</CardGroup>