Email filtering functionality broken in MCP server

[hnizdiljan]

Email filtering functionality broken in MCP server

Environment

• Client: Claude Desktop

Problem Description

The MCP server fails to properly filter emails when using the list-mail-messages tool. Multiple filtering approaches result in various errors, making it impossible to retrieve emails from specific senders.

Steps to Reproduce

1. Connect Claude Desktop to the MCP server
2. Request: "Find last 5 e-mails from karel.hnizdil@softim.cz"
3. Observe the MCP server attempting various filtering methods

Expected Behavior

The server should successfully filter and return the last 5 emails from the specified sender.

Actual Behavior

Multiple failed attempts with different error responses:

Attempt 1 - OData Filter

Request:

{ 
  "top": 5, 
  "filter": "from/emailAddress/address eq 'karel.hnizdil@softim.cz'", 
  "select": null, 
  "orderby": null 
}

Response:

Error executing code: Cannot convert undefined or null to object

Attempt 2 - Simplified Filter

Request:

{ 
  "top": 5, 
  "filter": "from/emailAddress/address eq 'karel.hnizdil@softim.cz'" 
}

Response:

{"error":"Microsoft Graph API error: 504 Gateway Timeout"}

Attempt 3 - Search Parameter

Request:

{ 
  "top": 5, 
  "search": "from:karel.hnizdil@softim.cz" 
}

Response:

{"error":"Microsoft Graph API error: 400 Bad Request"}

Attempt 4 - Large Result Set

Request:

{ "top": 50 }

Response:

result exceeds maximum length of 1048576

Analysis

The issues suggest multiple problems:

1. Null/undefined handling: The first error indicates improper handling of null/undefined values in filter parameters
2. OData filter syntax: The filter syntax may be incorrect for Microsoft Graph API
3. Search parameter format: The search syntax doesn't match Graph API expectations
4. Response size limits: Large responses exceed the MCP response size limit
5. API timeout: Some requests result in gateway timeouts

[nzhome]

honestly I would have thought this to be the first feature that an MS 365 mcp server would implement. I am disappointed.

The developer of this mcp doesn't understand real world mailboxes.

hnizdiljan, Have you found any better mcp servers with this functionality? can you link them here?

[eirikb]

This works for me.
The server has gone through some changes since the issue was created, I'm not sure if that could be the reason.
Honestly though this has worked for me for a long time, could be I have been lucky.
That being said it does tend to fail at least once, e.g., on sorting issues where the LLM tries to use something the API doesn't support.

I believe the core issue here is that the spec provided by Microsoft doesn't state how filters work - or perhaps they do and we just haven't exposed them properly to the client.

Is this issue still relevant, or should I investigate, @hnizdiljan?

[jake-marsden]

This works for me. The server has gone through some changes since the issue was created, I'm not sure if that could be the reason. Honestly though this has worked for me for a long time, could be I have been lucky. That being said it does tend to fail at least once, e.g., on sorting issues where the LLM tries to use something the API doesn't support.

I believe the core issue here is that the spec provided by Microsoft doesn't state how filters work - or perhaps they do and we just haven't exposed them properly to the client.

Is this issue still relevant, or should I investigate, @hnizdiljan?

The default query parameter descriptions exposed to the client are very simple. The $filter and $search descriptions don't contain essential information regarding syntax, encoding, etc. that is covered in the Microsoft Graph documentation here: https://learn.microsoft.com/en-us/graph/query-parameters?tabs=http, https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#_Toc31360955

I'm working on an implementation to expose custom, more detailed descriptions, while aiming to minimise context ahead.

[eirikb]

The default query parameter descriptions exposed to the client are very simple. The $filter and $search descriptions don't contain essential information regarding syntax, encoding, etc. that is covered in the Microsoft Graph documentation here: https://learn.microsoft.com/en-us/graph/query-parameters?tabs=http, https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#_Toc31360955

Yeah I think the LLM is using the description + it's own model to guess what should be passed - resulting in a lot of "misfires".

I'm working on an implementation to expose custom, more detailed descriptions, while aiming to minimise context ahead.

That's very interesting. Do you think it would be possible to add that to this server?

[jake-marsden]

The default query parameter descriptions exposed to the client are very simple. The $filter and $search descriptions don't contain essential information regarding syntax, encoding, etc. that is covered in the Microsoft Graph documentation here: https://learn.microsoft.com/en-us/graph/query-parameters?tabs=http, https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#_Toc31360955

Yeah I think the LLM is using the description + it's own model to guess what should be passed - resulting in a lot of "misfires".

I'm working on an implementation to expose custom, more detailed descriptions, while aiming to minimise context ahead.

That's very interesting. Do you think it would be possible to add that to this server?

I have worked through multiple iterations of prompt engineering but couldn't achieve an effective implementation, whether it was attaching custom detailed descriptions to the endpoints schema via src/generated/hack.ts so all tools receive the descriptions for those parameters it supports, or a dummy tool odata-query-parameters-reference acting as a global reference. The centralised descriptions were too abstract, and the model struggled to apply them correctly within specific contexts such as searching emails.

Maybe it's an issue of Claude Sonnet 4 not being well-trained on the Microsoft Graph API; I am unable to test more advanced models.

Therefore, I pivoted to a new strategy: sanitising and enforcing parameter constraints at the server level. Instead of relying on the model to perfectly formulate its requests, I implemented guardrails to programmatically enforce the APIs syntax and rules. This has been working well. For example:

if (paramName === '$search') {
  // Per Microsoft Graph API documentation, the $search query parameter value must be enclosed in double quotes.
  value = `"${String(value).replace(/"/g, '\\"')}"`;
}

I'm interested in hearing how other models have been performing. What model have you been using?

[eirikb]

@jake-marsden Sanitizing on the server is not a bad idea, it could help I think.
But a lot of the errors I see are from the LLM making wrong guesses on what is supported. What kind of fields it can sort by, or what types of filters are allowed etc..
However this is almost per endpoint.

[jake-marsden]

@eirikb Exactly! There is an excessive amount of rules, many of which are specific to endpoints. This is why I believe prompt engineering is inadequate as a standalone solution. If you choose to expose the complete parameter descriptions to the model, it would come at a huge context overhead. Since $filter and $search are the parameters that models struggle with the most, perhaps a combination of longer prompts and guardrails for these would result in a big performance improvement.

[eirikb]

@eirikb Exactly! There is an excessive amount of rules, many of which are specific to endpoints. This is why I believe prompt engineering is inadequate as a standalone solution. If you choose to expose the complete parameter descriptions to the model, it would come at a huge context overhead. Since $filter and $search are the parameters that models struggle with the most, perhaps a combination of longer prompts and guardrails for these would result in a big performance improvement.

Parameter description would help a ton, but yes it would be huge. The parameters are also not the same between endpoints so it would essentially be non-manageable - unless the agent would not load this, and only load the tools + description.
Could be it already does this, or it can be added as a feature if the server supports it. Then it would only send one and one tool into context.

[ctcanbol]

For "list-mail-message" tool, just adding a tip at the end of the description improved the one shot correct answers a lot!

 {
    "pathPattern": "/me/messages",
    "method": "get",
    "toolName": "list-mail-messages",
    "scopes": ["Mail.Read"],
    "llmTip": "CRITICAL: When searching emails, the $search parameter value MUST be wrapped in double quotes. Format: $search=\"your search query here\". Use KQL (Keyword Query Language) syntax to search specific properties: 'from:', 'subject:', 'body:', 'to:', 'cc:', 'bcc:', 'attachment:', 'hasAttachments:', 'importance:', 'received:', 'sent:'. Examples: $search=\"from:john@example.com\" | $search=\"subject:meeting AND hasAttachments:true\" | $search=\"body:urgent AND received>=2024-01-01\" | $search=\"from:john AND importance:high\". Remember: ALWAYS wrap the entire search expression in double quotes! Reference: https://learn.microsoft.com/en-us/graph/search-query-parameter"
  },

If it might be helpful, i can also create a PR for this implementation.

[eirikb]

For "list-mail-message" tool, just adding a tip at the end of the description improved the one shot correct answers a lot!

{
"pathPattern": "/me/messages",
"method": "get",
"toolName": "list-mail-messages",
"scopes": ["Mail.Read"],
"llmTip": "CRITICAL: When searching emails, the $search parameter value MUST be wrapped in double quotes. Format: $search="your search query here". Use KQL (Keyword Query Language) syntax to search specific properties: 'from:', 'subject:', 'body:', 'to:', 'cc:', 'bcc:', 'attachment:', 'hasAttachments:', 'importance:', 'received:', 'sent:'. Examples: $search="from:john@example.com" | $search="subject:meeting AND hasAttachments:true" | $search="body:urgent AND received>=2024-01-01" | $search="from:john AND importance:high". Remember: ALWAYS wrap the entire search expression in double quotes! Reference: https://learn.microsoft.com/en-us/graph/search-query-parameter"
},

If it might be helpful, i can also create a PR for this implementation.

Sure 🙂