Monica CRM MCP Server

Manage Monica conversations

monica_manage_conversation

Manage messages within Monica CRM conversations by listing, creating, updating, or deleting them to organize communication records.

Instructions

List, inspect, create, update, delete, or manage messages inside Monica conversations. Provide either contactFieldTypeId or contactFieldTypeName for the channel.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`action`	Yes
`conversationId`	No
`messageId`	No
`contactId`	No
`limit`	No
`page`	No
`payload`	No
`messagePayload`	No

Implementation Reference

src/tools/modules/communications.ts:52-393 (registration)

Registers the 'monica_manage_conversation' tool using server.registerTool, providing title, description, input schema, and the inline asynchronous handler function.

server.registerTool(
  'monica_manage_conversation',
  {
    title: 'Manage Monica conversations',
    description:
      'List, inspect, create, update, delete, or manage messages inside Monica conversations. Provide either contactFieldTypeId or contactFieldTypeName for the channel.',
    inputSchema: {
      action: z.enum([
        'list',
        'get',
        'create',
        'update',
        'delete',
        'addMessage',
        'updateMessage',
        'deleteMessage'
      ]),
      conversationId: z.number().int().positive().optional(),
      messageId: z.number().int().positive().optional(),
      contactId: z.number().int().positive().optional(),
      limit: z.number().int().min(1).max(100).optional(),
      page: z.number().int().min(1).optional(),
      payload: conversationPayloadSchema.optional(),
      messagePayload: conversationMessagePayloadSchema.optional()
    }
  },
  async ({ action, conversationId, messageId, contactId, limit, page, payload, messagePayload }) => {
    switch (action) {
      case 'list': {
        const response = await client.listConversations({ contactId, limit, page });
        const conversations = response.data.map(normalizeConversation);
        const scope = contactId ? `contact ${contactId}` : 'your account';
        const textSummary = conversations.length
          ? `Found ${conversations.length} conversation${conversations.length === 1 ? '' : 's'} for ${scope}.`
          : `No conversations found for ${scope}.`;

        return {
          content: [
            { type: 'text' as const, text: textSummary }
          ],
          structuredContent: {
            action,
            contactId,
            conversations,
            pagination: {
              currentPage: response.meta.current_page,
              lastPage: response.meta.last_page,
              perPage: response.meta.per_page,
              total: response.meta.total
            }
          }
        };
      }

      case 'get': {
        if (!conversationId) {
          return {
            isError: true as const,
            content: [
              { type: 'text' as const, text: 'Provide conversationId when retrieving a conversation.' }
            ]
          };
        }

        const response = await client.getConversation(conversationId);
        const conversation = normalizeConversation(response.data);
        const channel = conversation.channel.name;
        const contactName = conversation.contact?.name || `Contact ${conversation.contactId}`;

        return {
          content: [
            {
              type: 'text' as const,
              text: `Conversation ${conversationId} via ${channel} with ${contactName}. ${conversation.messages.length} message(s).`
            }
          ],
          structuredContent: {
            action,
            conversationId,
            conversation
          }
        };
      }

      case 'create': {
        if (!payload) {
          return {
            isError: true as const,
            content: [
              {
                type: 'text' as const,
                text: 'Provide happenedAt, contactFieldTypeId or contactFieldTypeName, and contactId when creating a conversation.'
              }
            ]
          };
        }

        let input: CreateConversationPayload;
        try {
          input = await toConversationCreatePayload(client, payload);
        } catch (error) {
          return {
            isError: true as const,
            content: [
              { type: 'text' as const, text: (error as Error).message }
            ]
          };
        }

        const response = await client.createConversation(input);
        const conversation = normalizeConversation(response.data);
        logger.info({ conversationId: conversation.id, contactId: conversation.contactId }, 'Created Monica conversation');

        return {
          content: [
            {
              type: 'text' as const,
              text: `Created conversation ${conversation.id} for contact ${conversation.contactId}.`
            }
          ],
          structuredContent: {
            action,
            conversation
          }
        };
      }

      case 'update': {
        if (!conversationId) {
          return {
            isError: true as const,
            content: [
              { type: 'text' as const, text: 'Provide conversationId when updating a conversation.' }
            ]
          };
        }

        if (!payload) {
          return {
            isError: true as const,
            content: [
              { type: 'text' as const, text: 'Provide happenedAt and channel info when updating a conversation.' }
            ]
          };
        }

        let input: UpdateConversationPayload;
        try {
          input = toConversationUpdatePayload(payload);
        } catch (error) {
          return {
            isError: true as const,
            content: [
              { type: 'text' as const, text: (error as Error).message }
            ]
          };
        }

        const response = await client.updateConversation(conversationId, input);
        const conversation = normalizeConversation(response.data);
        logger.info({ conversationId }, 'Updated Monica conversation');

        return {
          content: [
            {
              type: 'text' as const,
              text: `Updated conversation ${conversationId}.`
            }
          ],
          structuredContent: {
            action,
            conversationId,
            conversation
          }
        };
      }

      case 'delete': {
        if (!conversationId) {
          return {
            isError: true as const,
            content: [
              { type: 'text' as const, text: 'Provide conversationId when deleting a conversation.' }
            ]
          };
        }

        const result = await client.deleteConversation(conversationId);
        logger.info({ conversationId }, 'Deleted Monica conversation');

        return {
          content: [
            { type: 'text' as const, text: `Deleted conversation ID ${conversationId}.` }
          ],
          structuredContent: {
            action,
            conversationId,
            result
          }
        };
      }

      case 'addMessage': {
        if (!conversationId) {
          return {
            isError: true as const,
            content: [
              { type: 'text' as const, text: 'Provide conversationId when adding a message.' }
            ]
          };
        }

        if (!messagePayload) {
          return {
            isError: true as const,
            content: [
              { type: 'text' as const, text: 'Provide message details when adding to a conversation.' }
            ]
          };
        }

        let input: CreateConversationMessagePayload;
        try {
          input = toConversationMessageCreatePayload(messagePayload);
        } catch (error) {
          return {
            isError: true as const,
            content: [
              { type: 'text' as const, text: (error as Error).message }
            ]
          };
        }

        const response = await client.addConversationMessage(conversationId, input);
        const conversation = normalizeConversation(response.data);
        logger.info({ conversationId, contactId: input.contactId }, 'Added Monica conversation message');

        return {
          content: [
            {
              type: 'text' as const,
              text: `Added message to conversation ${conversationId}.`
            }
          ],
          structuredContent: {
            action,
            conversationId,
            conversation
          }
        };
      }

      case 'updateMessage': {
        if (!conversationId || !messageId) {
          return {
            isError: true as const,
            content: [
              { type: 'text' as const, text: 'Provide conversationId and messageId when updating a message.' }
            ]
          };
        }

        if (!messagePayload) {
          return {
            isError: true as const,
            content: [
              { type: 'text' as const, text: 'Provide message details when updating a conversation message.' }
            ]
          };
        }

        let input: UpdateConversationMessagePayload;
        try {
          input = toConversationMessageUpdatePayload(messagePayload);
        } catch (error) {
          return {
            isError: true as const,
            content: [
              { type: 'text' as const, text: (error as Error).message }
            ]
          };
        }

        const response = await client.updateConversationMessage(conversationId, messageId, input);
        const conversation = normalizeConversation(response.data);
        logger.info({ conversationId, messageId }, 'Updated Monica conversation message');

        return {
          content: [
            {
              type: 'text' as const,
              text: `Updated message ${messageId} in conversation ${conversationId}.`
            }
          ],
          structuredContent: {
            action,
            conversationId,
            messageId,
            conversation
          }
        };
      }

      case 'deleteMessage': {
        if (!conversationId || !messageId) {
          return {
            isError: true as const,
            content: [
              { type: 'text' as const, text: 'Provide conversationId and messageId when deleting a conversation message.' }
            ]
          };
        }

        const result = await client.deleteConversationMessage(conversationId, messageId);
        logger.info({ conversationId, messageId }, 'Deleted Monica conversation message');

        return {
          content: [
            {
              type: 'text' as const,
              text: `Deleted message ${messageId} from conversation ${conversationId}.`
            }
          ],
          structuredContent: {
            action,
            conversationId,
            messageId,
            result
          }
        };
      }

      default:
        return {
          isError: true as const,
          content: [
            { type: 'text' as const, text: `Unsupported action: ${action}.` }
          ]
        };
    }
  }
);

src/tools/modules/communications.ts:78-392 (handler)

The inline handler function that handles all tool actions by switching on 'action' and calling appropriate MonicaClient methods for listing, retrieving, creating, updating, deleting conversations and managing their messages.

async ({ action, conversationId, messageId, contactId, limit, page, payload, messagePayload }) => {
  switch (action) {
    case 'list': {
      const response = await client.listConversations({ contactId, limit, page });
      const conversations = response.data.map(normalizeConversation);
      const scope = contactId ? `contact ${contactId}` : 'your account';
      const textSummary = conversations.length
        ? `Found ${conversations.length} conversation${conversations.length === 1 ? '' : 's'} for ${scope}.`
        : `No conversations found for ${scope}.`;

      return {
        content: [
          { type: 'text' as const, text: textSummary }
        ],
        structuredContent: {
          action,
          contactId,
          conversations,
          pagination: {
            currentPage: response.meta.current_page,
            lastPage: response.meta.last_page,
            perPage: response.meta.per_page,
            total: response.meta.total
          }
        }
      };
    }

    case 'get': {
      if (!conversationId) {
        return {
          isError: true as const,
          content: [
            { type: 'text' as const, text: 'Provide conversationId when retrieving a conversation.' }
          ]
        };
      }

      const response = await client.getConversation(conversationId);
      const conversation = normalizeConversation(response.data);
      const channel = conversation.channel.name;
      const contactName = conversation.contact?.name || `Contact ${conversation.contactId}`;

      return {
        content: [
          {
            type: 'text' as const,
            text: `Conversation ${conversationId} via ${channel} with ${contactName}. ${conversation.messages.length} message(s).`
          }
        ],
        structuredContent: {
          action,
          conversationId,
          conversation
        }
      };
    }

    case 'create': {
      if (!payload) {
        return {
          isError: true as const,
          content: [
            {
              type: 'text' as const,
              text: 'Provide happenedAt, contactFieldTypeId or contactFieldTypeName, and contactId when creating a conversation.'
            }
          ]
        };
      }

      let input: CreateConversationPayload;
      try {
        input = await toConversationCreatePayload(client, payload);
      } catch (error) {
        return {
          isError: true as const,
          content: [
            { type: 'text' as const, text: (error as Error).message }
          ]
        };
      }

      const response = await client.createConversation(input);
      const conversation = normalizeConversation(response.data);
      logger.info({ conversationId: conversation.id, contactId: conversation.contactId }, 'Created Monica conversation');

      return {
        content: [
          {
            type: 'text' as const,
            text: `Created conversation ${conversation.id} for contact ${conversation.contactId}.`
          }
        ],
        structuredContent: {
          action,
          conversation
        }
      };
    }

    case 'update': {
      if (!conversationId) {
        return {
          isError: true as const,
          content: [
            { type: 'text' as const, text: 'Provide conversationId when updating a conversation.' }
          ]
        };
      }

      if (!payload) {
        return {
          isError: true as const,
          content: [
            { type: 'text' as const, text: 'Provide happenedAt and channel info when updating a conversation.' }
          ]
        };
      }

      let input: UpdateConversationPayload;
      try {
        input = toConversationUpdatePayload(payload);
      } catch (error) {
        return {
          isError: true as const,
          content: [
            { type: 'text' as const, text: (error as Error).message }
          ]
        };
      }

      const response = await client.updateConversation(conversationId, input);
      const conversation = normalizeConversation(response.data);
      logger.info({ conversationId }, 'Updated Monica conversation');

      return {
        content: [
          {
            type: 'text' as const,
            text: `Updated conversation ${conversationId}.`
          }
        ],
        structuredContent: {
          action,
          conversationId,
          conversation
        }
      };
    }

    case 'delete': {
      if (!conversationId) {
        return {
          isError: true as const,
          content: [
            { type: 'text' as const, text: 'Provide conversationId when deleting a conversation.' }
          ]
        };
      }

      const result = await client.deleteConversation(conversationId);
      logger.info({ conversationId }, 'Deleted Monica conversation');

      return {
        content: [
          { type: 'text' as const, text: `Deleted conversation ID ${conversationId}.` }
        ],
        structuredContent: {
          action,
          conversationId,
          result
        }
      };
    }

    case 'addMessage': {
      if (!conversationId) {
        return {
          isError: true as const,
          content: [
            { type: 'text' as const, text: 'Provide conversationId when adding a message.' }
          ]
        };
      }

      if (!messagePayload) {
        return {
          isError: true as const,
          content: [
            { type: 'text' as const, text: 'Provide message details when adding to a conversation.' }
          ]
        };
      }

      let input: CreateConversationMessagePayload;
      try {
        input = toConversationMessageCreatePayload(messagePayload);
      } catch (error) {
        return {
          isError: true as const,
          content: [
            { type: 'text' as const, text: (error as Error).message }
          ]
        };
      }

      const response = await client.addConversationMessage(conversationId, input);
      const conversation = normalizeConversation(response.data);
      logger.info({ conversationId, contactId: input.contactId }, 'Added Monica conversation message');

      return {
        content: [
          {
            type: 'text' as const,
            text: `Added message to conversation ${conversationId}.`
          }
        ],
        structuredContent: {
          action,
          conversationId,
          conversation
        }
      };
    }

    case 'updateMessage': {
      if (!conversationId || !messageId) {
        return {
          isError: true as const,
          content: [
            { type: 'text' as const, text: 'Provide conversationId and messageId when updating a message.' }
          ]
        };
      }

      if (!messagePayload) {
        return {
          isError: true as const,
          content: [
            { type: 'text' as const, text: 'Provide message details when updating a conversation message.' }
          ]
        };
      }

      let input: UpdateConversationMessagePayload;
      try {
        input = toConversationMessageUpdatePayload(messagePayload);
      } catch (error) {
        return {
          isError: true as const,
          content: [
            { type: 'text' as const, text: (error as Error).message }
          ]
        };
      }

      const response = await client.updateConversationMessage(conversationId, messageId, input);
      const conversation = normalizeConversation(response.data);
      logger.info({ conversationId, messageId }, 'Updated Monica conversation message');

      return {
        content: [
          {
            type: 'text' as const,
            text: `Updated message ${messageId} in conversation ${conversationId}.`
          }
        ],
        structuredContent: {
          action,
          conversationId,
          messageId,
          conversation
        }
      };
    }

    case 'deleteMessage': {
      if (!conversationId || !messageId) {
        return {
          isError: true as const,
          content: [
            { type: 'text' as const, text: 'Provide conversationId and messageId when deleting a conversation message.' }
          ]
        };
      }

      const result = await client.deleteConversationMessage(conversationId, messageId);
      logger.info({ conversationId, messageId }, 'Deleted Monica conversation message');

      return {
        content: [
          {
            type: 'text' as const,
            text: `Deleted message ${messageId} from conversation ${conversationId}.`
          }
        ],
        structuredContent: {
          action,
          conversationId,
          messageId,
          result
        }
      };
    }

    default:
      return {
        isError: true as const,
        content: [
          { type: 'text' as const, text: `Unsupported action: ${action}.` }
        ]
      };
  }
}

src/tools/modules/communications.ts:14-47 (schema)

Zod schemas for validating conversationPayload and conversationMessagePayload inputs used in the tool's inputSchema.

const conversationPayloadSchema = z.object({
  happenedAt: z
    .string()
    .regex(/^[0-9]{4}-[0-9]{2}-[0-9]{2}$/u, 'happenedAt must use YYYY-MM-DD format.')
    .optional(),
  contactFieldTypeId: z.number().int().positive().optional(),
  contactFieldTypeName: z.string().min(1).max(255).optional(),
  contactId: z.number().int().positive().optional()
});

type ConversationPayloadForm = z.infer<typeof conversationPayloadSchema>;

const conversationMessagePayloadSchema = z.object({
  writtenAt: z
    .string()
    .regex(/^[0-9]{4}-[0-9]{2}-[0-9]{2}$/u, 'writtenAt must use YYYY-MM-DD format.')
    .optional(),
  writtenByMe: z.boolean().optional(),
  content: z.string().min(1).max(1_000_000).optional(),
  contactId: z.number().int().positive().optional()
});

type ConversationMessagePayloadForm = z.infer<typeof conversationMessagePayloadSchema>;

const callPayloadSchema = z.object({
  calledAt: z
    .string()
    .regex(/^[0-9]{4}-[0-9]{2}-[0-9]{2}$/u, 'calledAt must use YYYY-MM-DD format.')
    .optional(),
  contactId: z.number().int().positive().optional(),
  content: z.string().max(1_000_000).optional().nullable()
});

type CallPayloadForm = z.infer<typeof callPayloadSchema>;

src/tools/modules/communications.ts:595-667 (helper)

Helper functions to transform and validate form payloads into API payloads for creating/updating conversations and messages, including resolving contact field types.

async function toConversationCreatePayload(
  client: ToolRegistrationContext['client'],
  payload: ConversationPayloadForm
): Promise<CreateConversationPayload> {
  if (!payload.happenedAt) {
    throw new Error('Provide happenedAt when creating a conversation.');
  }

  if (typeof payload.contactId !== 'number') {
    throw new Error('Provide contactId when creating a conversation.');
  }

  const contactFieldTypeId = await resolveContactFieldTypeId(client, {
    contactFieldTypeId: payload.contactFieldTypeId,
    contactFieldTypeName: payload.contactFieldTypeName
  });

  return {
    happenedAt: payload.happenedAt,
    contactFieldTypeId,
    contactId: payload.contactId
  };
}

function toConversationUpdatePayload(payload: ConversationPayloadForm): UpdateConversationPayload {
  if (!payload.happenedAt) {
    throw new Error('Provide happenedAt when updating a conversation.');
  }

  return {
    happenedAt: payload.happenedAt
  };
}

function toConversationMessageCreatePayload(
  payload: ConversationMessagePayloadForm
): CreateConversationMessagePayload {
  if (
    typeof payload.contactId !== 'number' ||
    !payload.writtenAt ||
    typeof payload.writtenByMe !== 'boolean' ||
    !payload.content
  ) {
    throw new Error('Provide contactId, writtenAt, writtenByMe, and content when adding a conversation message.');
  }

  return {
    contactId: payload.contactId,
    writtenAt: payload.writtenAt,
    writtenByMe: payload.writtenByMe,
    content: payload.content
  };
}

function toConversationMessageUpdatePayload(
  payload: ConversationMessagePayloadForm
): UpdateConversationMessagePayload {
  if (
    typeof payload.contactId !== 'number' ||
    !payload.writtenAt ||
    typeof payload.writtenByMe !== 'boolean' ||
    !payload.content
  ) {
    throw new Error('Provide contactId, writtenAt, writtenByMe, and content when updating a conversation message.');
  }

  return {
    contactId: payload.contactId,
    writtenAt: payload.writtenAt,
    writtenByMe: payload.writtenByMe,
    content: payload.content
  };
}

Tool Definition Quality

C2.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. While it lists the available actions, it doesn't explain what each action does, what permissions are required, whether operations are destructive, what happens to related data, or what the response format looks like. For a tool with 8 parameters including nested objects and multiple mutation actions, this is a significant gap in behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is reasonably concise with two sentences, but the structure could be improved. The first sentence tries to cover too many actions (list, inspect, create, update, delete, manage) which makes it somewhat vague. The second sentence provides specific parameter guidance but feels tacked on rather than integrated. While not verbose, it lacks the front-loaded clarity that would help an agent quickly understand the tool's core function.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (8 parameters including nested objects, multiple actions including mutations), lack of annotations, and no output schema, the description is inadequate. It doesn't explain the relationship between conversation and message operations, doesn't provide examples of when to use different actions, and doesn't cover error conditions or response formats. For a multi-action tool with significant parameter complexity, this description leaves too much unexplained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It only mentions two parameters (contactFieldTypeId or contactFieldTypeName) out of 8 total parameters. It doesn't explain the relationship between action and required parameters, what payload and messagePayload contain, or how conversationId, messageId, contactId, limit, and page are used. The description adds minimal value beyond what the bare schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verbs (list, inspect, create, update, delete, manage) and resource (Monica conversations). It distinguishes from sibling tools like monica_list_contacts and monica_manage_contact by focusing specifically on conversations rather than contacts or other entities. However, it doesn't explicitly differentiate from monica_manage_activity which might also involve conversation-like interactions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides minimal usage guidance. It mentions 'Provide either contactFieldTypeId or contactFieldTypeName for the channel' which is a parameter requirement, but doesn't explain when to use this tool versus alternatives like monica_manage_contact or monica_manage_activity. There's no guidance on which action to choose for specific scenarios, nor any prerequisites or constraints for using different actions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

Latest Blog Posts

Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security
Open Source Has a Bot Problem
By punkpeye on March 19, 2026.
open source

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Jacob-Stokes/monica-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server