home / mcp / mcp task mcp server
Reason and perform tasks using MCP. Use state of the art LLMs in your development workflows.
Configuration
View docs{
"mcpServers": {
"just-every-mcp-task": {
"command": "npx",
"args": [
"-y",
"@just-every/mcp-task"
],
"env": {
"ENV_FILE": "YOUR_ENV_FILE_PATH",
"XAI_API_KEY": "your-xai-key",
"BRAVE_API_KEY": "your-brave-key",
"GOOGLE_API_KEY": "your-google-key",
"OPENAI_API_KEY": "your-openai-key",
"ANTHROPIC_API_KEY": "your-anthropic-key",
"OPENROUTER_API_KEY": "your-openrouter-key",
"PERPLEXITY_API_KEY": "your-perplexity-key"
}
}
}
}This MCP server enables you to run long-running AI tasks with real-time progress monitoring. It orchestrates multiple AI models, tracks task status, and exposes simple commands to start, monitor, retrieve results, or cancel tasks, making it ideal for complex problem-solving workflows and automated experiment pipelines.
You integrate the MCP server with your existing MCP client configuration to start tasks, monitor progress, and fetch results. Start a task by sending a run command to the MCP server, then periodically poll for status to see live progress. Retrieve the final output once the task completes, and you can cancel tasks if needed. You can also run multiple tasks in a batch and wait for any or all of them to finish.
Key actions you’ll perform with a client: - Start a long-running task with a chosen model or set of models. - Check real-time progress and events as the task executes. - Retrieve the final result when the task finishes. - Cancel one or more tasks if you need to halt execution. - Wait for a specific task or any in a batch to complete, with a configurable timeout.
Prerequisites: you need Node.js and npm installed on your system. Ensure you have network access to reach AI model providers and any optional web/search services you plan to use.
Step 1: Create or use an environment file
Option A: Create a new environment file in your home directory and populate it with your API keys and settings:
``
# Download example env file
curl -o ~/.llm.env https://raw.githubusercontent.com/just-every/mcp-task/main/.env.example
# Edit with your API keys
nano ~/.llm.env
`
Option B: Use an existing environment file with an absolute path:
`
# Example: /Users/yourname/projects/myproject/.env
# Example: /home/yourname/workspace/.env
``
Step 2: Install and start the MCP task server using a client
Option A: Using a client that supports MCP servers (example shows how to add the task server to a client session):
```
claude mcp add task -s user -e ENV_FILE=$HOME/.llm.env -- npx -y @just-every/mcp-task
```
Option B: If you already have an MCP client configuration, add the following server entry for the task server:
```
{
"mcpServers": {
"task": {
"command": "npx",
"args": ["-y", "@just-every/mcp-task"],
"env": {
"ENV_FILE": "/path/to/.llm.env"
}
}
}
}
```
Option C: From the command line directly, you can run the server for debugging:
```
ENV_FILE=~/.llm.env npx @just-every/mcp-task
```
Option D: If you prefer a globally installed CLI, you can install and run the server startup command:
```
npm install -g @just-every/mcp-task
ENV_FILE=~/.llm.env mcp-task serveAPI keys must be provided for the AI models you intend to use. Place them in your environment file as shown in the API Keys section. You can manage keys for Anthropic, OpenAI, Grok (xAI), Google Gemini, and optional web search providers.
Environment variables influence how the server runs. You can pass ENV_FILE to point to your environment file. The server supports additional tuning through timeout and health settings described later in this guide.
Tasks progress through a defined lifecycle: Pending, Running, Completed, Failed, or Cancelled. Tasks are automatically cleaned up after 24 hours to keep the system tidy.
// 1. Start a task
const startResponse = await callTool('run_task', {
"model": "standard",
"task": "Search for the latest AI news and summarize",
"output": "A bullet-point summary of 5 recent AI developments"
});
// Returns: { "task_id": "abc-123", "status": "pending", ... }
// 2. Check progress
const statusResponse = await callTool('check_task_status', {
"task_id": "abc-123"
});
// Returns: { "status": "running", "progress": "Searching for AI news...", ... }
// 3. Get result when complete
const resultResponse = await callTool('get_task_result', {
"task_id": "abc-123"
});
// Returns: The complete summaryConfigure timeouts to prevent tasks from running indefinitely. Use the provided timeout, inactivity, and health check intervals to detect stalled tasks and recover gracefully. Ensure that read-only or restricted modes are used for tasks that should not modify files or system state.
If a task shows as failed, verify that API keys are correctly configured and that the environment file is accessible. Use absolute paths for the ENV_FILE value. For progress issues, check the live status and review recent events and tool calls.
Default timeouts are set for typical long-running tasks, with options to adjust via environment variables. Safety features include automatic timeout handling, inactivity detection, and regular health monitoring to ensure progress.
# Clone the project
git clone https://github.com/just-every/mcp-task.git
cd mcp-task
# Install dependencies
npm install
# Build for production
npm run buildStart a long-running AI task asynchronously and receive a task or batch ID for tracking.
Get real-time progress updates for a running task including status, progress, events, and tool calls.
Retrieve the final output of a completed task.
Cancel a pending or running task or an entire batch of tasks.
Wait for a specific task or any task in a batch to complete, with optional timeout and return options.
List all tasks with their current status and optional filters for status or batch.