MCP Server

Easy8 provides a built-in MCP server on the /mcp endpoint.

This endpoint exposes selected Easy8 functionality as MCP tools so that MCP-capable clients can discover tools, call them, and work with Easy8 issues and projects in a structured way.

What is MCP

MCP stands for Model Context Protocol.

In practice, it is a JSON-RPC based protocol that allows an AI client to:

• initialize a connection to a server
• discover available tools
• call those tools with structured arguments
• receive structured responses back

In Easy8, the MCP server is focused on issue and project workflows.

Endpoint

Use the standard Easy8 application URL and append /mcp.

Example:

https://your-easy8.example.com/mcp

Discovery

Easy8 publishes an MCP Server Card for pre-connection discovery at:

https://your-easy8.example.com/.well-known/mcp/server-card.json

The card advertises the Streamable HTTP transport on /mcp, server metadata, API key authentication, and the currently supported tool capability. It is public discovery metadata; the /mcp endpoint itself still follows the Enable MCP setting and API authentication rules.

How to enable the MCP server

The MCP server is disabled by default.

To enable it:

1. Open Easy8 administration.
2. Go to Settings.
3. Open the AI tab.
4. Enable Enable MCP.
5. Save the settings.

When MCP is disabled, the /mcp endpoint returns 404 Not Found.

Authentication

The MCP endpoint uses the standard Easy8 API authentication model.

• POST /mcp accepts API authentication
• use the Easy8 API key in the X-Redmine-API-Key header
• permissions are still enforced by Easy8 visibility and authorization rules

Example:

POST /mcp HTTP/1.1 Host: your-easy8.example.com Content-Type: application/json X-Redmine-API-Key: <your-api-key>

If the API key is missing or invalid, the endpoint returns 401 Unauthorized.

Behaviour summary

• GET /mcp returns 405 Method Not Allowed when MCP is enabled
• GET /mcp returns 404 Not Found when MCP is disabled
• POST /mcp returns 404 Not Found when MCP is disabled
• notifications without id return empty responses with 202 Accepted or 204 No Content depending on the method

MCP methods

The Easy8 MCP server currently supports these protocol methods.

initialize

Initializes the MCP session and returns server metadata, protocol version, and declared capabilities.

Example request:

{ "jsonrpc": "2.0", "id": 1, "method": "initialize" }

Example response:

{ "jsonrpc": "2.0", "id": 1, "result": { "protocolVersion": "2025-11-25", "capabilities": { "tools": { "listChanged": false } }, "serverInfo": { "name": "easy8-mcp", "title": "Easy8 MCP", "version": "0.1.0", "description": "Easy8 MCP server" } } }

ping

Simple health-style method. Returns an empty result.

tools/list

Returns the list of available MCP tools together with their JSON schemas.

Use this to discover the tool catalog dynamically.

tools/call

Calls one of the available Easy8 tools.

The request must include the tool name and tool arguments.

Example:

{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "easy8_issues_get", "arguments": { "id": 123 } } }

notifications/initialized

Supported as a client notification after initialization.

This notification does not require an id.

Available tools

easy8_projects_list

Lists visible projects.

Use it when the client needs to resolve a project before creating or filtering issues.

Arguments:

• limit - maximum number of projects to return
• offset - pagination offset
• name - project name filter
• easy_query_q - free-text query

easy8_issues_list

Lists visible issues.

Arguments:

• limit - maximum number of issues to return
• offset - pagination offset
• project_id - filter by project
• assigned_to_id - filter by assignee
• status - high-level status filter, open or closed
• status_id - specific status ID or list of IDs
• subject - subject text filter
• easy_query_q - free-text query
• due_date_period - relative due date filter

easy8_issues_get

Returns one visible issue by ID.

Arguments:

• id - issue ID

The response includes issue metadata, description, and comments_count.

easy8_issues_comments_list

Lists visible issue journal notes ordered from newest to oldest.

Arguments:

• id - issue ID
• limit - maximum number of comments
• offset - pagination offset

easy8_issues_create

Creates a new issue.

Arguments include:

• project selectors: project_id, projectId, project, project_name, project_identifier
• subject aliases: subject, title, name
• issue fields: tracker_id, description, assigned_to_id, priority_id, status_id, start_date, due_date
• custom fields: custom_fields

Notes:

• the issue subject is required
• a project selector is required
• permissions are checked with standard Easy8 authorization
• required custom fields are validated server-side

easy8_issues_update

Updates an existing issue.

• id - issue ID
• subject
• description
• assigned_to_id
• priority_id
• status_id
• start_date
• due_date
• notes - appends a new comment to the issue journal

Example workflow

Typical flow for an MCP client:

1. Call initialize.
2. Call tools/list.
3. Call easy8_projects_list or easy8_issues_list to discover context.
4. Call easy8_issues_get for detail.
5. Call easy8_issues_create or easy8_issues_update if the user has permission.

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

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

Troubleshooting

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