MCP Server

Aimdoc exposes a remote Model Context Protocol (MCP) server so AI assistants like Claude can read your Aimdoc data — conversations, contacts, visitor profiles, accounts, and activity timelines — and configure agents and services directly in chat.

Use it to ask questions like "How did this week go?", "Show me recent leads from Acme Corp", or "What did this visitor do before they booked a demo?" With a user-authorized connection, you can also create and update agents and services, then publish draft changes after review.

Overview

Server URL:

https://api.aimdoc.ai/mcp

The server uses Streamable HTTP transport. Read tools are backed by the same data layer as the External API. Agent and service configuration tools edit a draft and only reach customers after you publish.

When connected, your assistant can:

• Summarize activity with aggregate counts
• Search and read conversation transcripts
• Look up captured contacts and leads
• Explore visitor profiles and enrichment data
• Browse accounts (companies), ICP fit, CRM match, and usage
• Review visitor journeys and on-site activity
• List, create, and update agents, including form fields, websites, objectives, and skills
• Add Q&A pairs to the organization knowledge base
• Publish draft agent changes after you approve them
• List, create, and update services, including tools, access, automations, event triggers, and pricing
• Publish a service draft after you approve the diff
• Inspect your connected MCP servers and call their read-only tools

Connect with Claude

The recommended way to connect is through an MCP client that supports OAuth 2.1, such as Claude or Claude Code.

1. In your MCP client, add a remote MCP server with URL https://api.aimdoc.ai/mcp
2. The client discovers Aimdoc's OAuth endpoints automatically and starts the authorization flow
3. Sign in to your Aimdoc dashboard if prompted
4. Review the consent screen and approve access for your organization
5. The client receives an access token and can call MCP tools on your behalf

During consent, you grant access to conversations, contacts, visitor profiles, accounts, agent configuration, and services for your organization.

OAuth access tokens expire after 1 hour. MCP clients that support refresh tokens will rotate them automatically. You can revoke access at any time from your Aimdoc dashboard.

Connect with an API key

For custom MCP clients or programmatic access, authenticate with an API key instead of OAuth.

Server URL:

https://api.aimdoc.ai/mcp

Authorization header:

Authorization: Bearer ak_your_api_key_here

Create an API key the same way as the REST API:

• Go to Integrations
• Open API Keys
• Click Create new key
• Copy and store the key securely

API keys share the same rate limits and read access as OAuth tokens. Tools that create, update, or publish agents or services, or add knowledge-base Q&A pairs, are not available to API-key credentials — use a user-authorized OAuth connection for those.

Available tools

Start with get_usage_summary for aggregate questions, then drill into specific records. Use list_accounts when you need company-level context, then pass account_id into the search tools.

get_organization_info

Confirm which Aimdoc organization the connection is authenticated as. Returns the organization id, name, and created_at. For the companies engaging with you, use list_accounts instead.

No parameters.

get_usage_summary

Get aggregate activity counts for a date range: total conversations, conversations with visitor interaction, contacts created, and journey event counts by type (meetings booked, escalations, buyer intent, and more).

This tool is available on MCP only — there is no matching REST endpoint.

search_conversations

Search chat sessions between your AI sales agent and website visitors. Results are newest first and paginated.

REST equivalent: GET /api/v1/conversations

get_conversation

Get one conversation with its full message transcript in chronological order. Use conversation IDs from search_conversations.

REST equivalent: GET /api/v1/messages?conversation_id=... (MCP bundles conversation metadata and messages together).

search_contacts

Search contacts who shared their details — name, email, company — with your agent.

REST equivalent: GET /api/v1/contacts

list_visitor_profiles

List visitor profiles with identity and company enrichment, whether or not the visitor became a contact.

REST equivalent: GET /api/v1/visitor-profiles

get_visitor_profile

Get the full profile for one visitor: person identity, company enrichment, referrer context, associated contact, and latest conversation.

REST equivalent: GET /api/v1/visitor-profiles/{visitor_id}

get_visitor_journey

Get a visitor's activity timeline: journey events (session started, contact created, meeting booked, escalation, buyer intent, identification) and browser activity (page views, clicks).

Returns the most recent 50 of each event kind. Check each section's pagination.total to see if more events exist.

REST equivalent: GET /api/v1/visitor-journey-events and GET /api/v1/browser-events (MCP merges both into one response).

list_accounts

List accounts — companies engaging with your website or product, derived from contact work emails, visitor enrichment, or SDK identify. Each row includes contact and visitor counts, last activity, the cached CRM match, and the ICP fit score (1–100).

REST equivalent: GET /api/v1/accounts

get_account

Get one account's full profile: company facts, CRM match with account owner, ICP fit score with research findings, linked contacts and visitor profiles (first 50 of each), and the 10 most recent conversations. For complete people lists, filter search_contacts or list_visitor_profiles by account_id.

REST equivalent: GET /api/v1/accounts/{account_id}

get_account_activity

Get an account's engagement: daily usage, most active people, or top website pages.

REST equivalents: GET /api/v1/accounts/{account_id}/activity/daily, /activity/people, and /activity/pages.

Agent configuration tools

These tools inspect and edit agent drafts. Mutating tools require a user-authorized OAuth connection (not an API key). Nothing reaches visitors until you call publish_agent with confirm=true after reviewing pending changes.

list_agents

List the organization's agents with published and draft timestamps. Use this to find an agent_id before configuring or publishing.

No parameters.

get_agent

Get one agent's full draft configuration: name, persona, goal, conversation starters, data-capture fields, training websites, objectives, and unpublished changes.

create_agent

Create a new agent. Research the company first and write a substantive persona and goal. agent_type is website (default) or product (in-app). starters is up to 3 suggested opening questions.

update_agent

Update core draft settings. Only the parameters you pass change. persona and goal replace the current text entirely — read them with get_agent first.

update_agent_fields

Add, update, or remove data-capture form fields on the draft.

add_agent_website

Add a website to the agent's knowledge base and start crawling it. Attach happens on the draft — publish for trained knowledge to reach visitors.

add_qa_pairs

Add question-and-answer pairs to the organization knowledge base. Dynamic Q&A is global — every agent can retrieve the pairs immediately via knowledge search. There is no draft or publish_agent step.

Requires a user-authorized OAuth connection (not an API key).

create_agent_objective / update_agent_objective

Create or update a journey objective on the draft. key is a stable slug; level is account or person; optional stage, gating, completion_sources, and customer_facing match the Objectives tab. customer_facing true exposes the name (never the description) in the checklist your product reads through the Services SDK. Changes go live with publish_agent.

list_agent_skills / create_agent_skill

List or create skills on the draft. Skills combine activation rules, instructions, and granted tools. Workflow tracks and skills are mutually exclusive; tracks take precedence when enabled.

get_agent_workflow

Read the agent's legacy visitor workflow (tracks tree), typically to migrate it to skills. Workflow mode switches remain dashboard-only.

publish_agent

Publish draft changes so they go live for visitors.

Service authoring tools

These tools inspect and edit services. Mutating tools require a user-authorized OAuth connection (not an API key). Nothing is customer-visible until you publish a draft and the catalog listing is configured.

Call list_service_authoring_options before constructing tool bindings or access policy so you use real MCP server ids and valid enum values.

Read

• list_services / get_service / list_service_versions — catalog, draft vs published, live listing, and version history
• list_service_authoring_options — valid native tools, connected MCP servers, surfaces, acquisition modes, and capabilities
• preview_service_access — the catalog and allowed actions for a contact, account, or anonymous visitor
• get_service_run — status and result for one run
• list_service_access_requests — pending and decided access requests
• list_service_automations / list_service_event_subscriptions — standing work and event triggers
• get_service_price — the current price package (draft or active), the margin preview, anything blocking activation, and whether Stripe is ready

Write

• create_service / update_service / update_service_draft / configure_service_tools — identity, draft instructions, inputs, the optional target_credits / max_credits run budget, and tools. Prefer a stable idempotency_key on create.
• discard_service_draft / restore_service_version — throw away unpublished edits, or copy a published version back into the draft
• configure_service_offering — live listing, surfaces, and acquisition. Takes effect immediately; it is not part of a version.
• set_service_access_rule / grant_service_plan_access / revoke_service_plan_access / decide_service_access_request — who may discover, run, and automate. A plan grant can carry a counted allowance (limit plus a period of none or billing_period).
• configure_service_price / activate_service_price — write the draft price package (one-time or subscription, included runs, reset period) and review its margin preview, then make it live in your connected Stripe account. Activation archives the previous price; existing orders keep their terms.
• test_service_as_contact — run the draft or published version as a real contact. Tests are saved-only and never delivered to the customer.
• publish_service — always call with confirm=false first, review the executable diff with the user, then call again with confirm=true
• Automation and event-trigger tools (create_service_automation, pause_service_automation, run_service_automation, create_service_event_subscription, and the matching update / resume / cancel / delete tools) — standing work for one customer, or "whenever this event fires, run this service"

See Services and Events for the product behavior these tools configure.

Connected MCP server tools

Two tools let your assistant look at the MCP servers you connected under Integrations without handing it their credentials:

• inspect_mcp_connection — list connected servers and the tool schemas Aimdoc discovered on them. Omit mcp_server_id to list every connection. Credentials and OAuth secrets are never returned.
• call_mcp_tool — call one tool on a connected server. Aimdoc supplies the stored credential server-side. Only tools that advertise themselves as read-only are callable this way; an optional reason is recorded for audit.

Authentication

The MCP server is an OAuth 2.1 resource server. It accepts two types of bearer tokens:

Both token types grant the api scope and access the same organization data for read tools. Only OAuth (or another user-backed credential) can call agent and service configuration writes, including publish_agent and publish_service.

Discovery endpoints

MCP clients use these well-known URLs to discover authentication:

• GET https://api.aimdoc.ai/.well-known/oauth-protected-resource/mcp — protected resource metadata
• GET https://api.aimdoc.ai/.well-known/oauth-authorization-server — authorization server metadata

Unauthenticated requests to /mcp return 401 with a WWW-Authenticate challenge pointing clients to these discovery documents.

Rate limits

MCP tool calls share the same rate limits as the External API:

• 1,000 requests per hour
• 10,000 requests per day

Limits are tracked per credential (API key or OAuth token family). When a limit is exceeded, the tool returns an error with a retry hint rather than an HTTP 429 response.

Related docs

• Services for authoring and delivering capabilities
• Events to emit product events and trigger services
• Agent Gateway for the public conversation MCP at /mcp/public/{agent_id}
• API & Webhooks Overview for REST API authentication and endpoints
• Objectives for journey goals agents track
• Skills for reusable agent behavior
• Webhooks Guide for real-time event delivery
• API Reference (Redoc) for full REST schemas and examples