> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://gtm-tools.sh/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://gtm-tools.sh/_mcp/server.

# Agent Onboarding

> Resources for AI coding assistants: MCP server, agent-friendly docs, and a single bearer token to LinkedIn, Reddit, email, and signal tools.

If you're developing with AI, GTM Tools offers several resources to improve your experience.

## Get an API key

Your agent can sign up programmatically through `get_api_key`. No console access needed: a 6-digit code is sent to the email you provide, and calling the same endpoint again with the code returns the bearer token.

**`cURL`**

```bash title="cURL"
# 1. Request a verification code
curl -X POST https://api.gtm-tools.sh/api/v0/get_api_key \
  -H "Content-Type: application/json" \
  -d '{"email": "you@yourcompany.com"}'

# 2. Re-call with the code from your inbox
curl -X POST https://api.gtm-tools.sh/api/v0/get_api_key \
  -H "Content-Type: application/json" \
  -d '{"email": "you@yourcompany.com", "code": "123456"}'
# → { "api_key": "sk_..." }
```

**`TypeScript`**

```typescript title="TypeScript"
// 1. Request a verification code
await fetch("https://api.gtm-tools.sh/api/v0/get_api_key", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "you@yourcompany.com" }),
});

// 2. Re-call with the code from your inbox
const res = await fetch("https://api.gtm-tools.sh/api/v0/get_api_key", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "you@yourcompany.com", code: "123456" }),
});
const { api_key } = await res.json();
```

**`CLI`**

```bash title="CLI"
# 1. Request a verification code
gtm-tools admin auth you@yourcompany.com

# 2. Re-run with the code from your inbox
gtm-tools admin auth you@yourcompany.com --code 123456
```

### Autonomous registration via `auth.md`

GTM Tools implements the [`auth.md` spec](https://workos.com/auth-md/docs/auth-md) so an autonomous agent that hits a 401 can register itself without a human signup form. The 401 carries `WWW-Authenticate: Bearer resource_metadata="https://api.gtm-tools.sh/.well-known/oauth-protected-resource"`; following that hop leads to the [auth.md narrative](https://api.gtm-tools.sh/auth.md) with copy-paste curl examples.

Two registration shapes are supported:

| Shape                                                                                              | When                                 | Outcome                                                                                                                                                                                                              |
| -------------------------------------------------------------------------------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `{"type":"anonymous"}`                                                                             | No user context                      | New isolated workspace + `sk_` key returned immediately. 100 free credits; free tools work out of the box.                                                                                                           |
| `{"type":"identity_assertion", "assertion_type":"verified_email", "assertion":"user@example.com"}` | Agent acts on behalf of a known user | 6-digit code emailed to the user; agent submits it via `/agent/identity/claim`, polls `/oauth/token` with `grant_type=urn:workos:agent-auth:grant-type:claim`, receives the `sk_` key bound to the user's workspace. |

**`Anonymous registration in one call`**

```bash title="Anonymous registration in one call"
curl -s -X POST https://api.gtm-tools.sh/agent/identity \
  -H "Content-Type: application/json" \
  -d '{"type":"anonymous"}'
# → { "access_token":"sk_...", "token_type":"bearer", "expires_in":31536000, "scope":"api", "organization_id":"org_..." }
```

Revoke at any time:

```bash
curl -X POST https://api.gtm-tools.sh/oauth/revoke \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'token=sk_...'
```

ID-JAG (`urn:ietf:params:oauth:token-type:id-jag`) is not yet accepted, since no agent provider mints them in production. We'll enable it when an issuer ships.

> **Info**
>
> New accounts receive **100 free credits** (\$1 = 100 credits, paid top-ups start at \$5). Live credit costs per tool are returned by `get_credit_balance`.

## GTM Tools MCP Server

[MCP (Model Context Protocol)](https://modelcontextprotocol.io) is an open protocol that standardizes how applications provide context to LLMs. The GTM Tools MCP server gives your AI agent tools to find LinkedIn profiles, engage on Reddit, verify professional emails, detect buying signals, and manage your wallet, all through a single Streamable HTTP endpoint.

### Setup

Point any MCP-compatible client at the endpoint:

```
https://api.gtm-tools.sh/mcp
```

On first connect, the server runs the OAuth flow via `/.well-known/oauth-protected-resource` and the client opens a browser to authenticate. Clients that prefer static keys can authenticate with `Authorization: Bearer <api-key>` instead.

The fastest path is the `mcp add` CLI, which patches Claude Desktop, Cursor, or Windsurf configs in place:

```bash
npx gtm-tools@latest mcp add --client claude-desktop
# Append `--with-api-key sk_...` to skip OAuth and embed a key.
```

For a manual config, point a `gtm-tools` MCP entry at the URL above. The full set of supported clients (Claude Desktop, Cursor, Windsurf, Codex, Goose, OpenClaw, Hermes Agent, NanoClaw, Raycast, VS Code, Cline, …) is on the [Connect](/connect) page.

### Available MCP tools

Your MCP client discovers tools directly from the hosted runtime, so there is nothing to declare on your side. See the [current MCP tool catalog](/integrations/mcp#tool-catalogue) for names and parameter shapes, and [Pricing](/pricing) for the credit cost of each one.

> **Info**
>
> `get_credit_balance` returns the live per-tool cost table. Agents should call it rather than hardcoding costs.

#### [MCP Server Setup](/integrations/mcp)

Connect to the hosted GTM Tools MCP server: endpoint, OAuth flow, tool annotations, and error codes.

## GTM Tools Docs for Agents

You can give your agent current docs in three ways:

1. **Full documentation index**

   A structured index of every doc page with descriptions:

   ```
   https://gtm-tools.sh/llms.txt
   ```

2. **Markdown versions of any page**

   Every doc page is available as Markdown. Append `.md` to any page URL:

   ```
   https://gtm-tools.sh/quickstart.md
   ```

3. **Section indexes**

   Append `/llms.txt` to any section URL for a scoped index:

   ```
   https://gtm-tools.sh/api-reference/llms.txt
   ```

Agents that would rather search than read can point an MCP client at the docs server itself, `https://gtm-tools.sh/_mcp/server`. Or add the index to your system prompt:

```
For GTM Tools usage, refer to: https://gtm-tools.sh/llms.txt
```

## GTM Tools Skills

Skills give AI agents specialized knowledge for specific tasks. Install the `gtm-tools` skill to give your coding assistant the whole tool surface: how to get a key, how to connect a browser session, the full 63-tool catalog with credit costs, the metering rules, and the error contract.

### Claude Code

```bash
npx skills add arnaudjnn/gtm-skills --skill gtm-tools
```

### Cursor

```bash
npx skills add arnaudjnn/gtm-skills --skill gtm-tools --agent cursor
```

### Codex

```bash
npx skills add arnaudjnn/gtm-skills --skill gtm-tools --agent codex
```

Other supported values for `--agent`: `amp`, `cline`, `gemini-cli`, `kimi-code-cli`, `opencode`, `windsurf`. Use `--agent '*'` for all of them, `--global` for a user-level install, and `--yes` to skip the prompts.

### Manual installation

```bash
git clone https://github.com/arnaudjnn/gtm-skills.git
cp -R gtm-skills/skills/gtm-tools ~/.claude/skills/gtm-tools
```

Then set your API key:

```bash
export GTM_TOOLS_API_KEY="sk_..."
```

#### [Skills on GitHub](https://github.com/arnaudjnn/gtm-skills)

View the skill source and full documentation.

## Quick start for agents

Get a key, qualify a target with signals, find decision-makers on LinkedIn, and verify their emails, end-to-end:

**`TypeScript`**

```typescript title="TypeScript"
const KEY = process.env.GTM_TOOLS_API_KEY!;
const HEADERS = {
  "Authorization": `Bearer ${KEY}`,
  "Content-Type": "application/json",
};

async function call<T>(tool: string, body: unknown = {}): Promise<T> {
  const res = await fetch(`https://api.gtm-tools.sh/api/v0/${tool}`, {
    method: "POST",
    headers: HEADERS,
    body: JSON.stringify(body),
  });
  if (!res.ok) throw new Error(`${tool}: ${res.status} ${await res.text()}`);
  return res.json();
}

// 1. Detect buying signals (free dispatch + 5 per detector that fires)
const signals = await call<any>("detect_signal", { domain: "gymshark.com" });

// 2. Find decision-makers (30 credits)
const employees = await call<any>("list_linkedin_company_employees", {
  domain: "gymshark.com",
  title_filters: "(VP OR Director OR Head) AND (CX OR Support) NOT intern",
  limit: 10,
});

// 3. Verify professional emails (5 credits each)
for (const e of employees.results.slice(0, 3)) {
  const { email, status, reason } = await call<any>("get_email", {
    name: e.name,
    domain: "gymshark.com",
  });
  console.log(e.name, "→", status === "ok" ? email : `no address (${reason})`);
}
```

**`cURL`**

```bash title="cURL"
KEY=$GTM_TOOLS_API_KEY

# 1. Detect buying signals
curl -X POST https://api.gtm-tools.sh/api/v0/detect_signal \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"domain": "gymshark.com"}'

# 2. Find decision-makers
curl -X POST https://api.gtm-tools.sh/api/v0/list_linkedin_company_employees \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"domain": "gymshark.com", "title_filters": "(VP OR Director) AND (CX OR Support)", "limit": 10}'

# 3. Verify a professional email
curl -X POST https://api.gtm-tools.sh/api/v0/get_email \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"name": "Ben Francis", "domain": "gymshark.com"}'
```

**`CLI`**

```bash title="CLI"
export GTM_TOOLS_API_KEY="sk_..."

# 1. Detect buying signals
gtm-tools signals detect gymshark.com

# 2. Find decision-makers
gtm-tools socials employees gymshark.com \
  --filter "(VP OR Director) AND (CX OR Support)" \
  --limit 10

# 3. Verify a professional email
gtm-tools email find --name "Ben Francis" --domain gymshark.com
```

### Browse a target's recent activity

```typescript
// Recent posts from a company's employees (80 credits)
const posts = await call<any>("list_linkedin_company_employees_posts", {
  company: "gymshark",
  max_employees: 5,
  days_back: 7,
});
```

## AI Builder Integrations

GTM Tools plugs into the runtime your agent already uses:

#### [OpenClaw](/integrations/openclaw)

Add GTM Tools to an OpenClaw assistant as an MCP server or a skill.

#### [Hermes Agent](/integrations/hermes)

Declare the MCP server in `~/.hermes/config.yaml` and reload.

#### [LangChain](/integrations/langchain)

Load every tool into a LangGraph agent through `langchain-mcp-adapters`.

#### [Eve](/integrations/eve)

An MCP connection with approval gates on the write tools.

## What Makes GTM Tools Different?

Unlike traditional GTM platforms, which are seat-licensed UIs that bolt on a partial REST API, GTM Tools is built for **autonomous agent use**:

| Feature                      | GTM Tools                           | Traditional GTM platforms           |
| ---------------------------- | ----------------------------------- | ----------------------------------- |
| Pricing model                | ✅ Per-tool credit metering          | ❌ Per-seat licenses                 |
| Getting started              | ✅ 100 free credits, no card         | ⚠️ 14–30 day demo, often gated      |
| Primary surface              | ✅ MCP + REST + CLI                  | ❌ UI with a partial REST API        |
| Agent self-registration      | ✅ `auth.md`, no signup form         | ❌ Human signup required             |
| LinkedIn + email + signals   | ✅ One bearer token                  | ❌ Several vendors stitched together |
| Writes from your own account | ✅ Pooled browser sessions           | ⚠️ Gated partner APIs               |
| Auto top-up                  | ✅ `set_auto_reload` on a saved card | ❌ Annual contract                   |
| Agent-friendly docs          | ✅ `llms.txt` + `.md` for every page | ❌ HTML only                         |

## Next Steps

#### [Full Quickstart Guide](/quickstart)

Step-by-step setup with environment variables and best practices.

#### [API Reference](/api-reference)

Full interactive API documentation.

#### [Example: Lead Enrichment](/lead-enrichment)

Batch-enrich a lead list with LinkedIn URLs and verified emails.

#### [FAQ](/faq)

Answers to common questions about auth, credits, rate limits, and tool behavior.