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:

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 for the active public product catalog. Premium Catch-All Recovery uses recovery-specific scopes and tools.

Create a Scoped Local Agent Key

1. Open API Keys

   Go to Dashboard → API Keys.

2. 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.

3. 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.

Claude Desktop Local Setup

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

{
  "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:

{
  "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:

{
  "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:

Use GTMAPIs docs to show me the canonical auth header, validation statuses, hosted MCP endpoint, and rate-limit guidance.

Validate [e-mail] with GTMAPIs and explain whether it is high-value for B2B outbound.

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.
• Use only products and operations in the current public catalog.

Related Docs

Authentication

Create keys, understand scopes, and store credentials safely.

OpenAPI Spec

Machine-readable public API reference for available-now endpoints.

Quickstart

Make your first validation request.

Rate Limits

Build agent workflows that respect retry and rate-limit headers.