MCP (Model Context Protocol)

The Model Context Protocol (MCP) provides a standardized interface for AI clients - such as Claude Desktop, Cursor, or custom agents - to interact with the Clears AI platform. Through MCP, external tools can search tasks, manage issues, read pull requests, and more, all using a consistent protocol.

Server Configuration

Endpoint

https://{host}/api/v1/mcp/

Replace {host} with your Clears AI instance hostname (e.g., api.clears.ai).

Authentication

MCP supports three authentication methods depending on the client type:

Method	Use Case	Format
HMAC-SHA256	Internal service-to-service calls	Signed request headers
Personal Access Token (PAT)	CLI tools and external AI clients	Bearer token with cl_pat_ prefix
Cognito JWT	Web application sessions	Standard JWT bearer token

Personal Access Token

PATs are the recommended method for connecting external AI clients. Generate a token from Settings > API Keys - tokens use the cl_pat_ prefix.

Example configuration for Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "clears": {
      "url": "https://api.clears.ai/api/v1/mcp/",
      "headers": {
        "Authorization": "Bearer cl_pat_your_token_here"
      }
    }
  }
}

Available Tools

MCP exposes 23 tools organized across six categories. Each tool includes annotation hints (readOnlyHint, destructiveHint, idempotentHint) so AI clients can make informed decisions about tool usage.

Board Tools

Tools for managing stories and interacting with the AI workflow.

Tool	Description	Read-Only
search_tasks	Search for stories and tasks by keyword, status, or assignee	Yes
perform_action	Execute a workflow action on a story (e.g., approve, start implementation)	No
get_qa_session	Retrieve the Q&A session for a story in analysis	Yes
submit_qa_answers	Submit answers to the AI's clarifying questions	No
discover_actions	List available actions for a story in its current state	Yes
run_task	Trigger a workflow run on a specific task	No

Issue Tools

Tools for reading and updating Jira issues linked to Clears AI.

Tool	Description	Read-Only
get_issue	Retrieve full details of an issue by key	Yes
update_issue_description	Update an issue's description field	No
update_issue_summary	Update an issue's summary/title	No
update_issue_assignee	Change the assignee of an issue	No
update_issue_reporter	Change the reporter of an issue	No
add_comment	Add a comment to an issue	No

Pull Request Tools

Tools for reviewing pull requests and listing repositories.

Tool	Description	Read-Only
read_pr	Read the full details of a pull request including diff and comments	Yes
comment_on_pr	Add a review comment to a pull request	No
list_repos	List all repositories connected to the workspace	Yes

Session Tools

Tools for interacting with AI execution sessions.

Tool	Description	Read-Only
read_ai_session	Read the log and state of an AI session	Yes
write_ai_session	Write data or instructions to an active AI session	No
get_run_status	Check the current status of a workflow run	Yes

Knowledge Tools

Tools for searching the platform's knowledge base and user stories.

Tool	Description	Read-Only
search_knowledge	Search the AI's accumulated knowledge documents	Yes
search_user_stories	Search across all user stories by keyword or filter	Yes

Utility Tools

General-purpose tools for connectivity and session management.

Tool	Description	Read-Only
ping	Test connectivity to the MCP server	Yes
search_sessions	Search across AI sessions by keyword or status	Yes
memory_search	Search the AI's memory for relevant context	Yes

Tool Annotations

Each tool carries annotation hints that help AI clients decide how to use it:

{
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": true
  }
}

Annotation	Meaning
readOnlyHint	The tool only reads data and does not modify state
destructiveHint	The tool may delete or irreversibly modify data
idempotentHint	Calling the tool multiple times with the same input produces the same result

AI clients can use these hints to, for example, auto-approve read-only tools while requiring confirmation for destructive ones.

Connecting External MCP Servers

Clears AI can also act as an MCP client, connecting to external MCP servers to give its AI agents additional capabilities. Configure external servers in Settings > AI Agent Tools.

For example, connecting a CloudWatch MCP server gives the AI agent access to log analysis and metric monitoring during implementation.