@vennyx/soliagile-mcp

An MCP (Model Context Protocol) server for SoliAgile — lets AI agents (Claude, Codex, or any MCP-compatible client) read and manage teams, issues, and boards through tools instead of raw API calls.

Built on @modelcontextprotocol/sdk ^1.29 and @vennyx/soliagile-sdk. Supports both stdio (the default — what most desktop MCP clients expect) and Streamable HTTP transports.

Configuration

The server reads its SoliAgile credentials from the environment:

| Variable | Required | Description | | ---------------------- | -------- | ----------------------------------------------------------------------------- | | SOLIAGILE_API_KEY | Yes | A tenant-scoped API key (sa_...) — see below. | | SOLIAGILE_BASE_URL | No | Overrides the API base URL (defaults to https://api.soliagile.com/api/v1). |

Create an API key from your tenant settings (owner/admin role, requires a Business plan or above):

POST /api/v1/tenants/:id/api-keys
Authorization: Bearer <your Zitadel JWT>
Content-Type: application/json

{ "name": "Claude Desktop" }

The response's plaintextKey field is shown only once — copy it into SOLIAGILE_API_KEY right away.

Usage with an MCP client (stdio)

Most desktop MCP clients (Claude Desktop, etc.) run the server via npx over stdio. Add this to your client's MCP server configuration:

{
  "mcpServers": {
    "soliagile": {
      "command": "npx",
      "args": ["-y", "@vennyx/soliagile-mcp"],
      "env": {
        "SOLIAGILE_API_KEY": "sa_..."
      }
    }
  }
}

Or run it directly:

SOLIAGILE_API_KEY=sa_... npx @vennyx/soliagile-mcp

Streamable HTTP

To run the server over Streamable HTTP instead (e.g. for a remote/shared deployment):

SOLIAGILE_API_KEY=sa_... npx @vennyx/soliagile-mcp --http 3939

The port argument is optional (defaults to 3939); the server listens on 127.0.0.1.

Embedding programmatically

import { createSoliAgileMcpServer } from '@vennyx/soliagile-mcp';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = createSoliAgileMcpServer({
  clientOptions: { apiKey: process.env.SOLIAGILE_API_KEY! },
});

await server.connect(new StdioServerTransport());

Or reuse an existing @vennyx/soliagile-sdk client instance:

import { SoliAgileClient } from '@vennyx/soliagile-sdk';
import { createSoliAgileMcpServer } from '@vennyx/soliagile-mcp';

const client = new SoliAgileClient({ apiKey: process.env.SOLIAGILE_API_KEY! });
const server = createSoliAgileMcpServer({ client });

Tools

| Tool | Description | | -------------------- | ---------------------------------------------------------------------------------- | | list_teams | Lists teams (cursor-paginated, optional name/key search). | | list_issues | Lists issues with filters (team, state, assignee, priority, label, project, text). | | get_issue | Fetches a single issue by id, including label ids. | | create_issue | Creates a new issue. | | update_issue | Updates fields on an existing issue. | | move_issue_state | Moves an issue to a different workflow state (board column), with ordering. | | search | Searches issue titles, optionally scoped to a team. | | get_board | Fetches a team's board (issues grouped by workflow state). |

All tools that hit an authorization or entitlement error (invalid/revoked API key, or a plan that no longer includes API access) surface the SoliAgile API's error message directly in the tool result.

License

MIT