MCP Integration

What is MCP?

Model Context Protocol (MCP) is an open standard that lets AI agents interact with external services through a standardized tool interface. DialogueDB hosts an MCP server so agents can store, search, and manage conversations directly — no custom integration code required.

Quick Connect — Claude Desktop

1. Create an OAuth client in the DialogueDB dashboard: Settings > OAuth Clients > Create. Copy the client_id and client_secret.
2. In Claude Desktop, go to Settings > MCP Servers > Add
3. Enter URL: https://api.dialoguedb.com/mcp/v1
4. Enter the client_id and client_secret
5. Claude Desktop will open a browser window for you to log in to your DialogueDB account and authorize access
6. Once authorized, Claude can use all DialogueDB tools

TIP

The same flow works with other MCP-compatible clients like Cursor and Windsurf. Enter the server URL and your OAuth credentials when prompted.

Available Tools

The hosted MCP server exposes 23 tools across five categories:

Dialogues

Tool	Description
list_dialogues	List dialogues with optional filters
create_dialogue	Create a new dialogue with an initial message
get_dialogue	Retrieve a dialogue by ID
update_dialogue	Update dialogue tags, label, state, or messages
delete_dialogue	Delete a dialogue
dialogue_action	Perform an action on a dialogue (e.g., end)
update_dialogue_state	Create or update dialogue state
list_dialogue_summaries	List dialogue summaries

Messages

Tool	Description
list_messages	List messages in a dialogue
create_message	Add a message to a dialogue
get_message	Retrieve a specific message
update_message	Update message tags
delete_message	Delete a message

Memory

Tool	Description
list_memories	List stored memories
create_memory	Create a new memory
get_memory	Retrieve a memory by ID
update_memory	Update memory tags
delete_memory	Delete a memory

Search

Tool	Description
search	Semantic search across dialogues, messages, and memories

Health

Tool	Description
ping	Check server connectivity

For full parameter details, see the API Reference.

Available Resources

MCP clients can discover the API schema at runtime using resource URIs:

URI	Description
entity://list	List all MCP-enabled entities with their base paths and methods
entity://{basePath}/schema	Get the full schema for an entity (properties, indexes, methods)
invoke://list	List invoke configurations
invoke://{configId}/schema	Get invoke config schema

These resources let agents introspect the available API surface without hardcoded knowledge of endpoints or schemas.

Authentication Methods

OAuth (Recommended for Interactive Clients)

OAuth is the recommended authentication method for interactive MCP clients like Claude Desktop. The flow works as follows:

1. Register an OAuth client in the DialogueDB dashboard to get a client_id and client_secret
2. The MCP client initiates an authorization code flow with PKCE
3. The user authenticates in their browser and grants access
4. A scoped access token is issued to the MCP client

OAuth discovery follows standard protocols:

• GET /mcp/v1 returns 401 with a WWW-Authenticate header pointing to the protected resource metadata
• /.well-known/oauth-protected-resource — RFC 9728 protected resource metadata
• /.well-known/oauth-authorization-server — RFC 8414 authorization server metadata

See the Authentication Guide for more details.

API Key (For Programmatic Clients)

For headless setups, CI pipelines, or custom MCP clients, pass your API key as a bearer token:

DIALOGUEDB_API_KEY=your_api_key_here

The MCP client sends this as the Authorization: Bearer header. No browser-based login is required.

Self-Hosted MCP Server

For air-gapped environments or custom tool subsets, the dialogue-db-mcp npm package can run a local MCP server:

npx dialogue-db-mcp

Set the DIALOGUEDB_API_KEY environment variable before running. The self-hosted server connects to DialogueDB's API on your behalf and exposes the same MCP tool interface.

See the dialogue-db-mcp package on npm for configuration options.

Next Steps

• Authentication — Set up API keys and OAuth clients
• API Reference — Full endpoint documentation
• Quickstart — Create your first conversation