Core Concepts

Socials Tools

socials-tools is the LinkedIn automation server. It exposes 19 tools for searching companies, resolving people, fetching profiles, browsing posts and jobs, listing employees with boolean title filters, and sending DMs and invitations. Sessions are managed by connect_linkedin so the same browser identity persists across calls.

Endpoint

https://socials.gtm-engine.sh
TransportPath
MCP/mcp
REST/api/v0/{tool_name}

Tools

ToolTokensDescription
connect_linkedin0Start a LinkedIn browser session
list_connected_linkedin_accounts0List connected LinkedIn accounts
get_linkedin_company_url2Find a company’s LinkedIn page from a domain
get_linkedin_profile_url5Find a person’s LinkedIn profile from name + company domain
get_linkedin_post2Get content of a LinkedIn post
get_linkedin_job2Get full details of a job listing
get_linkedin_profile4Get a LinkedIn profile
get_linkedin_company2Get company data
list_user_posts5List recent posts from a LinkedIn user
send_linkedin_message5Send a direct message
send_linkedin_invitation5Send a connection request
list_linkedin_conversations5List recent conversations
list_linkedin_jobs5List all jobs for a company
list_linkedin_company_employees30List/search employees with optional title filters
list_linkedin_company_posts5List recent company posts
list_linkedin_post_reactions5List people who reacted to a post
list_linkedin_post_comments5List comments on a post
list_linkedin_saved_posts10List saved posts with content
list_linkedin_company_employees_posts80Recent posts from a company’s employees

Sessions: connect_linkedin

The first time you use a write tool (send_linkedin_message, send_linkedin_invitation), call connect_linkedin to bind a browser session to your org. Read tools work without an explicit session.

$curl -X POST https://socials.gtm-engine.sh/api/v0/connect_linkedin \
>  -H "Authorization: Bearer $GTM_ENGINE_API_KEY"

The response includes a one-time URL where you sign in to LinkedIn. From that point on, calls inherit the session. list_connected_linkedin_accounts shows which sessions are active.

Resolving identifiers

The most common pattern is domain → company URL → employees → profile.

$# 1. Domain → company URL (2 tokens)
$curl -X POST https://socials.gtm-engine.sh/api/v0/get_linkedin_company_url \
>  -H "Authorization: Bearer $GTM_ENGINE_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{"domain": "siena.cx"}'
$
$# 2. Search employees with boolean title filters (30 tokens)
$curl -X POST https://socials.gtm-engine.sh/api/v0/list_linkedin_company_employees \
>  -H "Authorization: Bearer $GTM_ENGINE_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "domain": "siena.cx",
>    "title_filters": "(VP OR Director OR Head) AND Sales NOT intern",
>    "limit": 25,
>    "page": 1
>  }'
$
$# 3. Resolve a name + company domain to a profile URL (5 tokens)
$curl -X POST https://socials.gtm-engine.sh/api/v0/get_linkedin_profile_url \
>  -H "Authorization: Bearer $GTM_ENGINE_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{"name": "Andrei Negrau", "domain": "siena.cx"}'
$
$# 4. Hydrate the profile (4 tokens)
$curl -X POST https://socials.gtm-engine.sh/api/v0/get_linkedin_profile \
>  -H "Authorization: Bearer $GTM_ENGINE_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{"profile_url": "https://linkedin.com/in/andreinegrau"}'

Title filter syntax

list_linkedin_company_employees accepts boolean expressions in title_filters:

OperatorExample
AND"sales AND SaaS"
OR"engineer OR developer"
NOT"manager NOT intern"
Parentheses"(VP OR Director OR Head) AND Sales NOT intern"
Quoted phrase"\"customer success\" AND lead"

The same syntax works in the CLI’s --filter flag.

Posts and engagement

ToolReturns
get_linkedin_postFull post content + author + engagement counts
list_linkedin_post_reactionsPeople who reacted (+ reaction type)
list_linkedin_post_commentsComments + commenter profiles
list_user_postsRecent posts from a single profile
list_linkedin_company_postsRecent posts from a company page
list_linkedin_company_employees_postsRecent posts from every employee of a company (80 tokens — use sparingly)
list_linkedin_saved_postsPosts the connected account has saved

list_linkedin_company_employees_posts is by far the most expensive socials tool because it fans out across employees. Prefer list_linkedin_company_posts (5 tokens) when you only need official content, or scope to a known set of profile URLs with list_user_posts (5 tokens each).

Jobs

ToolDescription
list_linkedin_jobsAll jobs posted by a company
get_linkedin_jobFull description of a single posting

Combine with signal_hiring_role (in Signals Tools) to confirm hiring activity from multiple sources.

Outreach

send_linkedin_invitation and send_linkedin_message write to LinkedIn through the connected session. Both require connect_linkedin to have been called first.

ParameterTypeRequiredDescription
profile_urlstringYesLinkedIn profile URL of the recipient
messagestringYesMessage body (invitations: ≤ 300 chars)
$curl -X POST https://socials.gtm-engine.sh/api/v0/send_linkedin_invitation \
>  -H "Authorization: Bearer $GTM_ENGINE_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "profile_url": "https://linkedin.com/in/andreinegrau",
>    "message": "Hi Andrei — saw your post on CX agents. Would love to compare notes."
>  }'

list_linkedin_conversations returns recent threads so your agent can poll for replies.

Required environment variables (self-host)

VariableDescription
WORKOS_API_KEYAuth (production only — bypassed in dev)
STRIPE_SECRET_KEYBilling (production only — bypassed in dev)
WEB_TOOLS_API_KEYRequired — Bright Data / web-tools client key
WEB_TOOLS_URLRequired — base URL for the web-tools backend
RAPIDAPI_LINKEDIN_API_KEYRequired — fallback LinkedIn API
NEXT_PUBLIC_URLRequired — public URL

The hosted instance at socials.gtm-engine.sh has these set.

Next steps

Data Tools

Verify professional emails for the profiles you find.

Signals Tools

Detect buying intent on the same domains.

Outbound Sales Guide

Stitch socials + data + signals into a full prospecting workflow.