MCP Server

Aimdoc exposes a remote Model Context Protocol (MCP) server so AI assistants like Claude can read your account data — conversations, contacts, visitor profiles, and activity timelines — 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?"

Overview

Server URL:

https://api.aimdoc.ai/mcp

The server uses Streamable HTTP transport and exposes read-only tools backed by the same data layer as the External API. All tools are annotated as read-only — the MCP server does not modify your Aimdoc data.

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
• Review visitor journeys and on-site activity

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 read access to conversations, contacts, and visitor data 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 data access as OAuth tokens.

Available tools

The server exposes eight read-only tools. Start with get_usage_summary for aggregate questions, then drill into specific records.

get_account_info

Confirm which Aimdoc organization the connection is authenticated as. Returns the organization id, name, and created_at.

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

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.

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

• API & Webhooks Overview for REST API authentication and endpoints
• Webhooks Guide for real-time event delivery
• API Reference (Redoc) for full REST schemas and examples