MCP Server — PinglyMCP Developer Docs

Endpoint

https://mcp.pinglymcp.com

The legacy /mcp path remains a compatibility alias for existing clients. New clients should use the endpoint above.

Authorization

OAuth-capable MCP clients discover https://auth.pinglymcp.com automatically from the MCP protected-resource metadata and request the mcp:access scope. If you are already signed in, that authorization reuses your session.

resource: https://mcp.pinglymcp.com
scope:    mcp:access

You can also use a long-lived personal key from Dashboard → API Keys:

Authorization: Bearer pmcp_...

Agent skill

Add this reusable SKILL.md to an agent that supports skills. It contains connection guidance and safety notes, with no credentials. The buttons use the same text shown below.

Download SKILL.md

View agent skill source

---
name: pinglymcp
description: Use PinglyMCP's remote MCP server to inspect websites, find contact details, and manage credits safely.
---

# PinglyMCP

Use PinglyMCP through its Streamable HTTP MCP server:

`https://mcp.pinglymcp.com`

The `/mcp` path is a legacy alias. Prefer an MCP client with OAuth support. It can discover authorization through the server's protected-resource metadata; request the `mcp:access` scope for the canonical server resource. If OAuth is unavailable, use a PinglyMCP personal key as a bearer token. Keep the key secret: never print it, include it in shared output, or place it in source control.

## Discover tools and permissions

Call `tools/list` to see the tools available to this connection. For current service names, inputs, and behavior, consult `https://mcp.pinglymcp.com/llms-full.txt`. OAuth needs `billing:read` for billing reads or `billing:manage` for reads and changes. Personal keys use the dashboard's Billing access setting (None, Read or Manage), which applies to both REST billing endpoints and MCP billing tools; Manage includes Read. Personal-key MCP tool permissions are a separate allowlist: All tools includes current and future tools, while Selected tools exposes the complete non-billing tool list for selection. Changing Billing access synchronizes billing tools in a selected allowlist; existing custom allowlists remain as saved until Billing access or the tool selection changes. Billing calls still require the matching billing permission. Check `get_credit_balance` before making paid calls. Get the user's explicit confirmation before any billing mutation that may charge money or change a recurring plan. Preview subscription changes and review the preview with the user before applying them.

## Safe use

- Only submit public website targets. Do not ask PinglyMCP to access localhost, private or reserved IP ranges, or other non-public network targets. Do not use it to bypass access controls.
- `describe_website` costs credits. Its screenshot URL is accessible to anyone who has the link and expires after seven days; share it accordingly.
- `contact_website` can submit a form or send an email, causing a real external effect. Get the user's explicit confirmation for the specific contact action before calling it. If the outcome is uncertain, check available activity or ask the user; never blindly retry.
- Follow the user's instructions and the destination site's rules. Report tool results accurately and do not claim an action succeeded unless the result confirms it.

Service tools

Explore tool parameters and send a live call to the MCP server.

Ping

pingRead-only · free

Check public IPv4 addresses, IPv6 addresses, and domain names for network reachability. Costs 0 credits.

Response: Success returns ok, data.request, data.ping, and meta. Errors use stable product codes, retry guidance, and a request ID.

Try it live

API key

Sign in to select an account key. Creating a key will take you through sign in.

Required parameters

targetstringRequired

Public IPv4 address, IPv6 address, or domain name to check.

Request JSON

{
  "target": "example.com"
}

Live MCP request

Argument	Type	Required	Description
`target`	`string`	Yes	Public IPv4 address, IPv6 address, or domain name to check.

targetstring

Required

Public IPv4 address, IPv6 address, or domain name to check.

Example arguments

{
  "target": "example.com"
}

Describe Website

describe_websiteRead-only · uses credits

Render a public website, capture its viewport before AI analysis, and return a description, screenshot URL, and visible navigation links. Costs 1 credits.

Response: Success returns ok, data.request, data.page (requested/resolved URLs, title, screenshot), data.analysis, data.content, data.navigation, and meta. The screenshot URL is public to anyone with the link and expires after seven days. data.page.screenshot is null if capture or storage fails. data.navigation.links contains up to 12 visible links; data.navigation is null if the scan fails. Links are reported, not visited. Errors return ok: false, error (code, message, retryable, optional details), and meta.

Try it live

API key

Sign in to select an account key. Creating a key will take you through sign in.

Required parameters

urlstringRequired

Public HTTP(S) website URL to render and describe.

Optional parameters

instructionstringOptional

Optional focus for the visual description.

Request JSON

{
  "url": "https://example.com"
}

Live MCP request

Argument	Type	Required	Description
`url`	`string`	Yes	Public HTTP(S) website URL to render and describe.
`instruction`	`string`	No	Optional focus for the visual description.

urlstring

Required

Public HTTP(S) website URL to render and describe.

instructionstring

Optional

Optional focus for the visual description.

Example arguments

{
  "url": "https://example.com",
  "instruction": "Focus on the navigation and primary call to action."
}

Contact Website

contact_websiteExternal action · confirm first

Contact a website owner from a public URL by email or contact form, with optional AI-assistance for difficult form workflows. Costs 1 credits when completed without AI, or 10 credits when AI assistance is used.

Response: Success returns ok, data.request (effective contact values), data.page (requested/target URLs and optional screenshot), data.contact (method, status, submission, verification, confirmation), and meta (billing and safe debug summary). Email results additionally include data.contact.email with from (effective From address), replyTo (effective Reply-To address, or null when no header was sent), and status: accepted. Accepted confirms submission to the sending service, not inbox delivery. This optional object is absent for contact forms and may be absent in older results. Errors use stable product codes and retryable flags. An unconfirmed submission is never safe to retry automatically.

Email delivery behavior

Include the required email parameter in every request. Set it to an empty string to use the selected API key’s email account. Manage accounts in Dashboard → Emails and assign them in API Keys.

Email parameter / condition	Delivery behavior
email is an empty string (or whitespace)	Use the email account assigned to the API key. Send through its SMTP server with that account’s From address and no Reply-To header.
email matches the assigned account address (case-insensitive)	Send through the assigned SMTP server with the saved From address and no Reply-To header.
email is a different nonempty address, or nonempty with no assigned account	Send from hello@pinglymcp.com with the supplied email as Reply-To. The assigned SMTP credentials are not used.
email is blank and the key has no assigned account	Reject the request before execution or charging credits. Supply an email or assign an account to the key.
SMTP is selected but the account has not passed authentication	Reject the request; do not switch senders or resend through another transport.
Delivery uses a contact form	Use the supplied email in form fields, or the assigned address when blank. No SMTP message is sent.

email is an empty string (or whitespace)

Use the email account assigned to the API key. Send through its SMTP server with that account’s From address and no Reply-To header.

email matches the assigned account address (case-insensitive)

Send through the assigned SMTP server with the saved From address and no Reply-To header.

email is a different nonempty address, or nonempty with no assigned account

Send from hello@pinglymcp.com with the supplied email as Reply-To. The assigned SMTP credentials are not used.

email is blank and the key has no assigned account

Reject the request before execution or charging credits. Supply an email or assign an account to the key.

SMTP is selected but the account has not passed authentication

Reject the request; do not switch senders or resend through another transport.

Delivery uses a contact form

Use the supplied email in form fields, or the assigned address when blank. No SMTP message is sent.

OAuth requests have no personal-key email assignment, so provide a nonempty email for Reply-To. Saving an SMTP account checks authentication without sending a message; it does not guarantee inbox delivery.

Try it live

API key

Sign in to select an account key. Creating a key will take you through sign in.

Required parameters

urlstringRequired

Public HTTP(S) website URL to contact. A direct contact-page URL is allowed and its path/query are preserved.

namestringRequired

Sender name used for email Reply-To and contact-form fields. Tabs become spaces; other control characters are not allowed.

emailstringRequired · may be blank

Required parameter; supply a plain ASCII email address without quoted mailbox syntax, or an empty string to select the SMTP email assigned to your API key. A matching address also sends through SMTP without Reply-To. A different address sends from hello@pinglymcp.com with this address as Reply-To. Contact forms use this address or the assigned account address. A nonempty address is required when no email account is assigned.

subjectstringRequired

Email or contact-form subject. Tabs become spaces; other control characters are not allowed.

messagestringRequired

Message to send to the website owner.

Optional parameters

methodenumOptional

Delivery method. auto prefers contact via email. Choose your preferred contact method. Default: auto.

use_aibooleanOptional

Enable AI-assistance for automated contact-form discovery and submission. Default: false.

phonetic_namestringOptional

Optional phonetic spelling for contact forms that request it.

phone_number_extstringOptional

Optional phone country/area extension for contact forms.

phone_numberstringOptional

Optional phone number for contact forms.

statestringOptional

Optional state/region for contact forms.

citystringOptional

Optional city for contact forms.

Request JSON

{
  "url": "https://example.com/contact-us",
  "name": "Your Name",
  "email": "you@example.com",
  "subject": "Hello",
  "message": "I would like to get in touch.",
  "method": "auto",
  "use_ai": false
}

I understand this sends a real email or submits a contact form.

Live MCP request

Argument	Type	Required	Description
`url`	`string`	Yes	Public HTTP(S) website URL to contact. A direct contact-page URL is allowed and its path/query are preserved.
`name`	`string`	Yes	Sender name used for email Reply-To and contact-form fields. Tabs become spaces; other control characters are not allowed.
`email`	`string`	Yes · may be blank	Required parameter; supply a plain ASCII email address without quoted mailbox syntax, or an empty string to select the SMTP email assigned to your API key. A matching address also sends through SMTP without Reply-To. A different address sends from hello@pinglymcp.com with this address as Reply-To. Contact forms use this address or the assigned account address. A nonempty address is required when no email account is assigned.
`subject`	`string`	Yes	Email or contact-form subject. Tabs become spaces; other control characters are not allowed.
`message`	`string`	Yes	Message to send to the website owner.
`method`	`auto \| email \| contact_form`	No · default `"auto"`	Delivery method. auto prefers contact via email. Choose your preferred contact method.
`use_ai`	`boolean`	No · default `false`	Enable AI-assistance for automated contact-form discovery and submission.
`phonetic_name`	`string`	No	Optional phonetic spelling for contact forms that request it.
`phone_number_ext`	`string`	No	Optional phone country/area extension for contact forms.
`phone_number`	`string`	No	Optional phone number for contact forms.
`state`	`string`	No	Optional state/region for contact forms.
`city`	`string`	No	Optional city for contact forms.

urlstring

Required

Public HTTP(S) website URL to contact. A direct contact-page URL is allowed and its path/query are preserved.

namestring

Required

Sender name used for email Reply-To and contact-form fields. Tabs become spaces; other control characters are not allowed.

emailstring

Required · may be blank

Required parameter; supply a plain ASCII email address without quoted mailbox syntax, or an empty string to select the SMTP email assigned to your API key. A matching address also sends through SMTP without Reply-To. A different address sends from hello@pinglymcp.com with this address as Reply-To. Contact forms use this address or the assigned account address. A nonempty address is required when no email account is assigned.

subjectstring

Required

Email or contact-form subject. Tabs become spaces; other control characters are not allowed.

messagestring

Required

Message to send to the website owner.

methodauto | email | contact_form

Optional · Default: auto

Delivery method. auto prefers contact via email. Choose your preferred contact method.

use_aiboolean

Optional · Default: false

Enable AI-assistance for automated contact-form discovery and submission.

phonetic_namestring

Optional

Optional phonetic spelling for contact forms that request it.

phone_number_extstring

Optional

Optional phone country/area extension for contact forms.

phone_numberstring

Optional

Optional phone number for contact forms.

statestring

Optional

Optional state/region for contact forms.

citystring

Optional

Optional city for contact forms.

Example arguments

{
  "url": "https://example.com/contact-us",
  "name": "Your Name",
  "email": "you@example.com",
  "subject": "Hello",
  "message": "I would like to get in touch.",
  "method": "auto",
  "use_ai": false
}

Billing

A personal key’s Billing access setting applies to billing tools in MCP and billing endpoints in REST. Choose Read for billing reads or Manage for reads and changes; OAuth clients request billing:read or billing:manage alongside mcp:access. Billing calls cost zero credits. Reuse operationKey when retrying a mutation. Complete hosted Checkout before expecting purchased credits; preview subscription changes before confirming them. See Billing and credits for the payment workflow, operation states and sandbox guide.

Get billing account

get_billing_accountRead-only · uses credits

Read your subscription and credits. Requires billing:read. Costs 0 credits.

Try it live

API key

Sign in to select an account key. Creating a key will take you through sign in.

Request JSON

{}

Live MCP request

Argument	Type	Required	Description

Example arguments

{}

Get billing history

get_billing_historyRead-only · uses credits

Read purchases, invoices and refunds. Requires billing:read. Costs 0 credits.

Try it live

API key

Sign in to select an account key. Creating a key will take you through sign in.

Optional parameters

limitnumberOptional

Maximum number of records.

cursorstringOptional

Pagination cursor returned by the previous response.

Request JSON

{}

Live MCP request

Argument	Type	Required	Description
`limit`	`number`	No	Maximum number of records.
`cursor`	`string`	No	Pagination cursor returned by the previous response.

limitnumber

Optional

Maximum number of records.

cursorstring

Optional

Pagination cursor returned by the previous response.

Example arguments

{
  "limit": 20
}

Create credit top-up

create_credit_top_upExternal action · confirm first

Create a hosted payment link to buy credits. Payment must complete before credits are granted. Requires billing:manage. Costs 0 service credits.

Try it live

API key

Sign in to select an account key. Creating a key will take you through sign in.

Required parameters

topUpCentsnumberRequired

USD cents to spend, from 500 ($5) to 100000 ($1,000). Each cent buys one credit.

operationKeystringRequired

A unique key for this operation. Reuse the same key and arguments when retrying.

Request JSON

{
  "topUpCents": 500,
  "operationKey": "purchase-2026-09-27-001"
}

Create a payment link for this credit purchase?

Live MCP request

Argument	Type	Required	Description
`topUpCents`	`number`	Yes	USD cents to spend, from 500 ($5) to 100000 ($1,000). Each cent buys one credit.
`operationKey`	`string`	Yes	A unique key for this operation. Reuse the same key and arguments when retrying.

topUpCentsnumber

Required

USD cents to spend, from 500 ($5) to 100000 ($1,000). Each cent buys one credit.

operationKeystring

Required

A unique key for this operation. Reuse the same key and arguments when retrying.

Example arguments

{
  "topUpCents": 500,
  "operationKey": "purchase-2026-09-27-001"
}

Get billing operation

get_billing_operationRead-only · uses credits

Check whether a billing operation requires payment, is pending, or has completed. Requires billing:read. Costs 0 credits.

Try it live

API key

Sign in to select an account key. Creating a key will take you through sign in.

Required parameters

operationIdstringRequired

The operation ID returned when the operation was created.

Request JSON

{
  "operationId": "billing_operation_id"
}

Live MCP request

Argument	Type	Required	Description
`operationId`	`string`	Yes	The operation ID returned when the operation was created.

operationIdstring

Required

The operation ID returned when the operation was created.

Example arguments

{
  "operationId": "billing_operation_id"
}

Create subscription checkout

create_subscription_checkoutExternal action · confirm first

Create a hosted payment link for a new subscription. Requires billing:manage. Costs 0 service credits.

Try it live

API key

Sign in to select an account key. Creating a key will take you through sign in.

Required parameters

planenumRequired

The paid subscription plan.

operationKeystringRequired

A unique key for this operation. Reuse the same key and arguments when retrying.

Request JSON

{
  "plan": "developer",
  "operationKey": "purchase-2026-09-27-001"
}

Create a checkout for this recurring subscription?

Live MCP request

Argument	Type	Required	Description
`plan`	`developer \| startup`	Yes	The paid subscription plan.
`operationKey`	`string`	Yes	A unique key for this operation. Reuse the same key and arguments when retrying.

plandeveloper | startup

Required

The paid subscription plan.

operationKeystring

Required

A unique key for this operation. Reuse the same key and arguments when retrying.

Example arguments

{
  "plan": "developer",
  "operationKey": "purchase-2026-09-27-001"
}

Preview subscription change

preview_subscription_changeRead-only · uses credits

Preview an upgrade, downgrade, cancellation at renewal, reversal of cancellation, or removal of a scheduled downgrade while keeping the current plan. Upgrades require successful payment; downgrades apply at renewal. Requires billing:manage. Costs 0 credits.

Try it live

API key

Sign in to select an account key. Creating a key will take you through sign in.

Required parameters

actionenumRequired

The proposed subscription change.

Optional parameters

planenumOptional

Required for an upgrade or downgrade; omit for cancel, resume, or keep_current.

Request JSON

{
  "action": "upgrade"
}

Live MCP request

Argument	Type	Required	Description
`action`	`upgrade \| downgrade \| cancel \| resume \| keep_current`	Yes	The proposed subscription change.
`plan`	`developer \| startup`	No	Required for an upgrade or downgrade; omit for cancel, resume, or keep_current.

actionupgrade | downgrade | cancel | resume | keep_current

Required

The proposed subscription change.

plandeveloper | startup

Optional

Required for an upgrade or downgrade; omit for cancel, resume, or keep_current.

Example arguments

{
  "action": "upgrade",
  "plan": "developer"
}

Change subscription

change_subscriptionExternal action · confirm first

Confirm an unexpired preview. May charge the saved payment method for an upgrade. Review the preview before calling. Requires billing:manage. Costs 0 service credits.

Try it live

API key

Sign in to select an account key. Creating a key will take you through sign in.

Required parameters

previewIdstringRequired

The unexpired preview ID to confirm.

operationKeystringRequired

A unique key for this operation. Reuse the same key and arguments when retrying.

Request JSON

{
  "previewId": "billing_preview_id",
  "operationKey": "purchase-2026-09-27-001"
}

Apply this subscription preview, including its charges and effective date?

Live MCP request

Argument	Type	Required	Description
`previewId`	`string`	Yes	The unexpired preview ID to confirm.
`operationKey`	`string`	Yes	A unique key for this operation. Reuse the same key and arguments when retrying.

previewIdstring

Required

The unexpired preview ID to confirm.

operationKeystring

Required

A unique key for this operation. Reuse the same key and arguments when retrying.

Example arguments

{
  "previewId": "billing_preview_id",
  "operationKey": "purchase-2026-09-27-001"
}

Create billing portal session

create_billing_portal_sessionRead-only · uses credits

Create a private hosted link for payment methods and invoices. Share it only with the account owner. Requires billing:manage. Costs 0 credits.

Try it live

API key

Sign in to select an account key. Creating a key will take you through sign in.

Required parameters

operationKeystringRequired

A unique key for this operation. Reuse the same key and arguments when retrying.

Request JSON

{
  "operationKey": "purchase-2026-09-27-001"
}

Live MCP request

Argument	Type	Required	Description
`operationKey`	`string`	Yes	A unique key for this operation. Reuse the same key and arguments when retrying.

operationKeystring

Required

A unique key for this operation. Reuse the same key and arguments when retrying.

Example arguments

{
  "operationKey": "purchase-2026-09-27-001"
}

Personal key tool access

In Dashboard → API Keys, All tools grants current and future MCP tools and hides the tool list. Selected tools displays the complete non-billing tool list so you can choose which tools the key can list and run. Changing Billing access synchronizes the matching billing tools for a selected allowlist; an existing custom allowlist stays as saved until Billing access or the tool selection changes. Billing calls still require the matching Billing access permission, and MCP tool selection does not change REST access.

Utility tools

`get_account`

View the account connected to this MCP client.

Try it live

API key

Sign in to select an account key. Creating a key will take you through sign in.

This tool takes no parameters.

Request JSON

{}

Live MCP request

`get_credit_balance`

View current free monthly and purchased credits. Costs 0 credits.

Try it live

API key

Sign in to select an account key. Creating a key will take you through sign in.

This tool takes no parameters.

Request JSON

{}

Live MCP request

`hello`

Check the MCP connection with a greeting.

Try it live

API key

Sign in to select an account key. Creating a key will take you through sign in.

This tool takes no parameters.

Request JSON

{}

Live MCP request

MCP Inspector

npx @modelcontextprotocol/inspector@latest --cli \
  https://mcp.pinglymcp.com \
  --transport http \
  --method tools/list \
  --header "Authorization: Bearer YOUR_API_KEY"

Connect an MCP client

Endpoint

Authorization

Agent skill

Service tools

Ping

Describe Website

Contact Website

Email delivery behavior

Billing

Get billing account

Get billing history

Create credit top-up

Get billing operation

Create subscription checkout

Preview subscription change

Change subscription

Create billing portal session

Personal key tool access

Utility tools

get_account

get_credit_balance

hello

MCP Inspector

`get_account`

`get_credit_balance`

`hello`