Skip to content

MCP Security And Troubleshooting

Security and permissions

  • visibility checks use standard Easy8 visibility rules
  • tool actions respect regular Easy8 permissions such as issue creation and editing
  • the endpoint should only be enabled when it is intended for API clients or agent integrations

Write-tool safety

Write tools use Easy8 model visibility, permissions, validations, and safe_attributes where available.

The MCP server does not expose delete tools.

For spent-time corrections, clients should update the original time entry when appropriate and create replacement entries with easy8_time_entries_create. Before creating replacement entries on another project, call easy8_time_entry_activities_list for that target project or issue to choose a valid activity_id.

Validation errors and permission failures are returned as tool-level errors with isError: true.

Error handling

Expect both HTTP-level and JSON-RPC-level errors.

HTTP level examples:

  • 401 - missing or invalid API authentication
  • 404 - MCP disabled
  • 405 - unsupported HTTP method on /mcp

JSON-RPC level examples:

  • parse error for invalid JSON payloads
  • invalid request for malformed JSON-RPC payloads
  • method not found for unsupported MCP methods
  • tool-level business errors returned in tool output

/mcp returns 404

Check that Settings -> AI -> Enable MCP is enabled.

POST /mcp returns 401

Check that the request includes a valid Easy8 API key.

Tool call returns permission errors

Check the permissions of the API key owner in Easy8. The MCP server does not bypass Easy8 authorization.

Attachment read troubleshooting

easy8_issue_attachments_read scopes access to the visible issue given by id. It checks the parent attachment and, for a version read, the selected version permissions. An attachment or version belonging to another issue cannot be read by supplying its ID.

  • With version omitted or false, attachment_id must be an Attachment.id on the specified issue.
  • With version: true, attachment_id must be an AttachmentVersion.id, as used in /attachments/<id>?version=true. It is not the parent attachment ID or the version number.
  • There is no fallback to the other table when an ID is missing or inaccessible. Check the URL's version flag and the record's issue relationship instead of trying the same numeric ID in both modes.
  • For a version response, attachment.id remains the parent ID, while attachment.version_id and attachment.version identify the selected version. File metadata and bytes come from that selected version; privacy remains that of the parent attachment.

If an image is not available for analysis, inspect the complete MCP result.content array, not only the first text block. In auto mode, images detected from their bytes using Marcel have metadata in content[0].text and their original bytes encoded once as base64 in a separate type: "image" block with a detected mimeType. The filename or stored MIME label alone does not determine image handling. Unsupported non-image binary files remain metadata-only with analysis_supported: false. Explicit content_format: "text" forces a bounded UTF-8 text read instead of an image block.

There is no image-size limit, thumbnail generation, resizing, conversion, or truncation in the image path. Lowering max_bytes cannot make an auto image response smaller: that argument limits only text reads (default 256 KiB, maximum 1 MiB), including explicit content_format: "text".

Client/provider payload limits and image-format support are external constraints and are not bypassed by this code. If a response is rejected downstream, check those external limits and whether the client forwards standard MCP image blocks. Do not assume compatibility with a particular client or provider. Reading the complete original image requires memory proportional to the original file size plus its base64 representation; base64 alone is roughly one third larger than the original bytes, and response serialization can add further memory overhead.

Tool is missing from tools/list

For core tools, check that the service class loads successfully.

For plugin tools, check that the plugin is installed, enabled, and that its available_if predicate returns true.

Tool call returns validation errors

Check required fields, required custom fields, and project-specific workflow restrictions. MCP write tools reuse Easy8 model validations.