Skip to content

⭐️⭐️⭐️ Open-source, self-hosted alternative to Linear and Plane. Project management and issue tracking where teams and AI agents work side by side to plan and ship products.

feat(api): manage internal agents fully over MCP (#59)

Croff6cb16bca2af3
diff --git a/apps/api/src/__tests__/helpers/mcp.ts b/apps/api/src/__tests__/helpers/mcp.ts
new file mode 100644
index 00000000..30c8e9ea
--- /dev/null
+++ b/apps/api/src/__tests__/helpers/mcp.ts
@@ -0,0 +1,13 @@
+import { app } from '../../app';
+import { routeTools } from '../../mcp/generate';
+
+// The routes matching `match` that carry no MCP tool tag, as "METHOD /path". A route
+// opts in with mcpTool() in its detail, so a feature's test pins which of its routes
+// stay session-only.
+export function untaggedRoutes(match: (route: string) => boolean): string[] {
+ const tagged = new Set(routeTools(app).map((tool) => `${tool.method} ${tool.path}`));
+ return app.routes
+ .map((route) => `${route.method} ${route.path}`)
+ .filter(match)
+ .filter((route) => !tagged.has(route));
+}
diff --git a/apps/api/src/agent-skills/__tests__/integration/agent-skills.test.ts b/apps/api/src/agent-skills/__tests__/integration/agent-skills.test.ts
index c784a515..8d08d12b 100644
--- a/apps/api/src/agent-skills/__tests__/integration/agent-skills.test.ts
+++ b/apps/api/src/agent-skills/__tests__/integration/agent-skills.test.ts
@@ -2,8 +2,7 @@ import { describe, it, expect, beforeEach } from 'bun:test';
import { authedApi, type Api } from '../../../__tests__/helpers/app';
import { signUpTestUser } from '../../../__tests__/helpers/auth';
import { resetDb } from '../../../__tests__/helpers/db';
-import { routeTools } from '../../../mcp/generate';
-import { getMcpApp } from '../../../mcp/app-ref';
+import { untaggedRoutes } from '../../../__tests__/helpers/mcp';
// The project skill library: SKILL.md documents (plus optional reference files) given
// to internal agents. Content lives in the object store; the row holds metadata.
@@ -170,12 +169,9 @@ describe('agent skills', () => {
// A skill library is managed over MCP, so every route here is tagged except the file
// upload: an MCP call carries JSON, and uploading files is left to the UI.
it('exposes every skill route to MCP', () => {
- const app = getMcpApp();
- const tagged = new Set(routeTools(app).map((tool) => `${tool.method} ${tool.path}`));
- const untagged = app.routes
- .map((route) => `${route.method} ${route.path}`)
- .filter((route) => route.includes('agent-skills') || route.endsWith('/skills'))
- .filter((route) => !tagged.has(route));
+ const untagged = untaggedRoutes(
+ (route) => route.includes('agent-skills') || route.endsWith('/skills'),
+ );
expect(untagged).toEqual(['POST /projects/:projectKey/agent-skills/:skillId/references']);
});
diff --git a/apps/api/src/agent-tools/__tests__/integration/agent-tools.test.ts b/apps/api/src/agent-tools/__tests__/integration/agent-tools.test.ts
index 0cbb4d1a..929d32cf 100644
--- a/apps/api/src/agent-tools/__tests__/integration/agent-tools.test.ts
+++ b/apps/api/src/agent-tools/__tests__/integration/agent-tools.test.ts
@@ -2,6 +2,7 @@ import { describe, it, expect, beforeEach } from 'bun:test';
import { authedApi, type Api } from '../../../__tests__/helpers/app';
import { signUpTestUser } from '../../../__tests__/helpers/auth';
import { resetDb } from '../../../__tests__/helpers/db';
+import { untaggedRoutes } from '../../../__tests__/helpers/mcp';
// Configured tools for a project: a catalog tool bound to an integration credential.
// The secret lives on the credential, so a configured tool carries no secret. Access
@@ -115,6 +116,18 @@ describe('agent tools', () => {
expect(clear.data).toHaveLength(0);
});
+ // Over MCP a configured tool can be read and enabled on an agent, but binding one to
+ // a credential stays in the UI, where the credential is added.
+ it('exposes reading and enabling configured tools to MCP, not binding one', () => {
+ const untagged = untaggedRoutes(
+ (route) => route.includes('agent-tools') || route.includes('tool-configs'),
+ );
+ expect(untagged).toEqual([
+ 'POST /projects/:projectKey/agent-tools',
+ 'DELETE /projects/:projectKey/agent-tools/:agentToolId',
+ ]);
+ });
+
it('denies a non-member', async () => {
await setup();
const outsider = await signUpTestUser({ name: 'Outsider' });
diff --git a/apps/api/src/agent-tools/routes.ts b/apps/api/src/agent-tools/routes.ts
index 0c1ab981..077a8f0d 100644
--- a/apps/api/src/agent-tools/routes.ts
+++ b/apps/api/src/agent-tools/routes.ts
@@ -16,7 +16,10 @@ import {
} from './store';
const toolParams = t.Object({ projectKey: t.String(), agentToolId: t.Numeric() });
-const agentParams = t.Object({ projectKey: t.String(), agentId: t.Numeric() });
+const agentParams = t.Object({
+ projectKey: t.String(),
+ agentId: t.Numeric({ description: 'Agent id from list_ai_agents.' }),
+});
// A built-in agent action in the catalog (ToolMeta from ai-agents/runtime/tools).
// `always` marks the read-only actions granted unconditionally, that cannot be
@@ -43,10 +46,10 @@ const AgentToolResponse = t.Object({
// Two tool systems live under this tag. Built-in agent actions (create_issue,
// search_issues, ...) are the catalog an internal agent is granted through its
-// `tools` field; the catalog route is read-only, ai_agents-gated, and exposed over
-// MCP. Configured tools bind an external tool to an integration credential; those
-// reference secrets, so they are session-only (not MCP tools) and gated under the
-// agent_tools resource.
+// `tools` field; the catalog route is read-only and ai_agents-gated. Configured tools
+// bind an external tool to an integration credential and are gated under the
+// agent_tools resource; binding one to a credential is done in the UI, so only reading
+// them and enabling them on an agent are exposed over MCP.
export const agentToolRoutes = new Elysia({
name: 'agent-tools',
detail: { tags: ['Agent Tools'] },
@@ -83,7 +86,11 @@ export const agentToolRoutes = new Elysia({
},
detail: {
summary: 'List configured tools',
- description: "List a project's tools configured on integration credentials.",
+ description:
+ "List a project's tools configured on integration credentials. An id here is what " +
+ 'set_ai_agent_configured_tools takes to enable a tool on an agent. Separate from the ' +
+ 'built-in actions in list_ai_agent_tools.',
+ ...mcpTool('list_configured_tools'),
},
})
@@ -131,7 +138,6 @@ export const agentToolRoutes = new Elysia({
},
)
- // Which configured tools are enabled on an agent.
.get(
'/projects/:projectKey/ai-agents/:agentId/tool-configs',
async ({ params, project }) => {
@@ -152,11 +158,11 @@ export const agentToolRoutes = new Elysia({
detail: {
summary: "List an agent's enabled tools",
description: 'List the configured tools enabled on an agent.',
+ ...mcpTool('list_ai_agent_configured_tools'),
},
},
)
- // Replaces the set of configured tools enabled on an agent.
.put(
'/projects/:projectKey/ai-agents/:agentId/tool-configs',
async ({ params, project, body }) => {
@@ -167,7 +173,11 @@ export const agentToolRoutes = new Elysia({
return listAgentToolLinks(params.agentId);
},
{
- body: t.Object({ agentToolIds: t.Array(t.Number()) }),
+ body: t.Object({
+ agentToolIds: t.Array(t.Number(), {
+ description: 'Configured tool ids from list_configured_tools.',
+ }),
+ }),
params: agentParams,
permission: ['agent_tools', 'edit'],
response: {
@@ -179,7 +189,10 @@ export const agentToolRoutes = new Elysia({
},
detail: {
summary: "Set an agent's enabled tools",
- description: 'Replace the set of configured tools enabled on an agent.',
+ description:
+ 'Replace the set of configured tools enabled on an agent. Send the full set: a tool ' +
+ 'left out is disabled.',
+ ...mcpTool('set_ai_agent_configured_tools'),
},
},
);
diff --git a/apps/api/src/ai-agents/__tests__/integration/ai-agents.test.ts b/apps/api/src/ai-agents/__tests__/integration/ai-agents.test.ts
index 21cae913..04957c35 100644
--- a/apps/api/src/ai-agents/__tests__/integration/ai-agents.test.ts
+++ b/apps/api/src/ai-agents/__tests__/integration/ai-agents.test.ts
@@ -2,6 +2,7 @@ import { describe, it, expect, beforeEach } from 'bun:test';
import { authedApi, type Api } from '../../../__tests__/helpers/app';
import { signUpTestUser } from '../../../__tests__/helpers/auth';
import { resetDb } from '../../../__tests__/helpers/db';
+import { untaggedRoutes } from '../../../__tests__/helpers/mcp';
// AI agents attached to a project. Each agent is backed by a hidden bot user, owns a
// better-auth API key, and is a project member acting under a project role. An
@@ -364,4 +365,18 @@ describe('ai agents', () => {
const res = await agents(asOwner)({ agentId: created.data!.agent.id }).run.post({ prompt: '' });
expect(res.status).toBe(400);
});
+
+ // An agent is set up and talked to entirely over MCP. What stays out serves the chat
+ // UI: the streamed run and the caller's own thread history, plus this agent's run
+ // history — the analytics routes carry the project-wide run feed MCP reads instead.
+ it('exposes agent management and the run to MCP', () => {
+ const untagged = untaggedRoutes((route) => route.includes('/ai-agents'));
+ expect(untagged).toEqual([
+ 'GET /projects/:projectKey/ai-agents/:agentId/runs',
+ 'POST /projects/:projectKey/ai-agents/:agentId/run/stream',
+ 'GET /projects/:projectKey/ai-agents/:agentId/threads',
+ 'GET /projects/:projectKey/ai-agents/:agentId/threads/:threadId/messages',
+ 'DELETE /projects/:projectKey/ai-agents/:agentId/threads/:threadId',
+ ]);
+ });
});
diff --git a/apps/api/src/ai-agents/routes.ts b/apps/api/src/ai-agents/routes.ts
index 68fdbfe7..4e312bc5 100644
--- a/apps/api/src/ai-agents/routes.ts
+++ b/apps/api/src/ai-agents/routes.ts
@@ -21,7 +21,10 @@ import { listAgentRuns } from './run-queue';
import { listChatThreads, getChatThreadMessages, deleteChatThread } from './runtime/memory';
import { isOwnChatThread } from './runtime/thread-ids';
-const agentParams = t.Object({ projectKey: t.String(), agentId: t.Numeric() });
+const agentParams = t.Object({
+ projectKey: t.String(),
+ agentId: t.Numeric({ description: 'Agent id from list_ai_agents.' }),
+});
const threadParams = t.Object({
projectKey: t.String(),
agentId: t.Numeric(),
@@ -32,8 +35,10 @@ const threadParams = t.Object({
// agent has memory enabled; omit it to start a new thread (the id used is returned in
// the response).
const runBody = t.Object({
- prompt: t.String({ minLength: 1 }),
- threadId: t.Optional(t.String()),
+ prompt: t.String({ minLength: 1, description: 'Message to send the agent.' }),
+ threadId: t.Optional(
+ t.String({ description: 'Thread id from an earlier run, to continue that conversation.' }),
+ ),
});
// Run options for an interactive chat run (the test chat): the caller owns the memory
@@ -66,12 +71,29 @@ const username = t.String({
// over time. Ignored (stored as null/empty) for an external agent.
const configFields = {
modelCredentialId: t.Optional(
- t.Nullable(t.Number({ description: 'Integration credential id for the LLM provider.' })),
+ t.Nullable(
+ t.Number({
+ description:
+ 'Credential id of the LLM provider, from list_integration_credentials. Required for an ' +
+ 'internal agent to run.',
+ }),
+ ),
+ ),
+ model: t.Optional(
+ t.Nullable(
+ t.String({
+ description:
+ "Model id the provider offers, from list_provider_models, e.g. 'claude-sonnet-5'.",
+ }),
+ ),
),
- model: t.Optional(t.Nullable(t.String({ description: 'Model id, e.g. claude-sonnet-5.' }))),
instructions: t.Optional(t.Nullable(t.String({ description: 'System prompt for the agent.' }))),
tools: t.Optional(
- t.Array(t.String(), { description: 'Granted tool keys from list_ai_agent_tools.' }),
+ t.Array(t.String(), {
+ description:
+ 'Built-in action keys from list_ai_agent_tools the agent is granted. Tools on an ' +
+ 'integration are granted separately, through set_ai_agent_configured_tools.',
+ }),
),
temperature: t.Optional(t.Nullable(t.Number({ description: 'Sampling temperature.' }))),
maxSteps: t.Optional(t.Nullable(t.Integer({ description: 'Max tool-call steps per run.' }))),
@@ -85,7 +107,11 @@ const configFields = {
triggerOnAssign: t.Optional(t.Boolean({ description: 'Run when assigned to an issue.' })),
roleId: t.Optional(
t.Nullable(
- t.Integer({ description: 'project_role the bot acts under; null uses the default role.' }),
+ t.Integer({
+ description:
+ 'Role from list_roles the bot acts under, capping what its tools may do; null uses the ' +
+ 'default role.',
+ }),
),
),
};
@@ -378,9 +404,7 @@ export const aiAgentRoutes = new Elysia({ name: 'ai-agents', detail: { tags: ['A
},
)
- // Runs an internal agent against a prompt and returns its generated text. The
- // agent is built from its stored model configuration (Mastra). External agents
- // have no config and return 400.
+ // The agent is built from its stored model configuration (Mastra).
.post(
'/projects/:projectKey/ai-agents/:agentId/run',
async ({ params, project, body, user }) =>
@@ -403,7 +427,9 @@ export const aiAgentRoutes = new Elysia({ name: 'ai-agents', detail: { tags: ['A
},
detail: {
summary: 'Run an AI agent',
- description: 'Run an internal AI agent with a prompt and return its text.',
+ description:
+ 'Send a prompt to an internal AI agent and return its answer. Only an internal agent ' +
+ 'runs here; an external one has no model config and returns 400.',
...mcpTool('run_ai_agent'),
},
},
diff --git a/apps/api/src/integrations/__tests__/integration/integrations.test.ts b/apps/api/src/integrations/__tests__/integration/integrations.test.ts
index 836b9bf8..9825f64e 100644
--- a/apps/api/src/integrations/__tests__/integration/integrations.test.ts
+++ b/apps/api/src/integrations/__tests__/integration/integrations.test.ts
@@ -2,6 +2,7 @@ import { describe, it, expect, beforeEach } from 'bun:test';
import { authedApi, type Api } from '../../../__tests__/helpers/app';
import { signUpTestUser } from '../../../__tests__/helpers/auth';
import { resetDb } from '../../../__tests__/helpers/db';
+import { untaggedRoutes } from '../../../__tests__/helpers/mcp';
// Integration credentials for a project: one store for LLM provider keys (kind 'llm')
// and tool credentials (kind 'tool'). The secret is stored encrypted and never
@@ -121,6 +122,17 @@ describe('integrations', () => {
expect((await integrations(asOwner).get()).data).toHaveLength(0);
});
+ // An agent's provider and model are picked over MCP, so the reads are tagged. The
+ // writes are not: a credential body carries the provider's secret in plain text.
+ it('exposes the credential reads to MCP, not the writes', () => {
+ const untagged = untaggedRoutes((route) => route.includes('integrations'));
+ expect(untagged).toEqual([
+ 'POST /projects/:projectKey/integrations',
+ 'PATCH /projects/:projectKey/integrations/:credentialId',
+ 'DELETE /projects/:projectKey/integrations/:credentialId',
+ ]);
+ });
+
it('denies a non-member', async () => {
await setup();
const outsider = await signUpTestUser({ name: 'Outsider' });
diff --git a/apps/api/src/integrations/routes.ts b/apps/api/src/integrations/routes.ts
index 2fe6d517..51b10f65 100644
--- a/apps/api/src/integrations/routes.ts
+++ b/apps/api/src/integrations/routes.ts
@@ -4,6 +4,7 @@ import { guards } from '../shared/guards';
import { authContext } from '../shared/auth-context';
import { HttpError } from '../shared/lib';
import { ErrorResponse } from '../shared/responses';
+import { mcpTool } from '../mcp/generate';
import { INTEGRATION_CATALOG } from './catalog';
import { listModelsForProvider } from './models';
import { listCredentials, createCredential, updateCredential, deleteCredential } from './store';
@@ -46,8 +47,9 @@ const IntegrationResponse = t.Object({
const ProviderModelResponse = t.Object({ id: t.String(), name: t.String() });
-// Integration credentials carry secrets, so these routes are managed only through the
-// session UI and are not exposed as MCP tools. Gated under the integrations resource.
+// Gated under the integrations resource. The reads are exposed as MCP tools, so an
+// internal agent's provider and model can be picked without the UI; the writes are
+// not, because a credential body carries the provider's secret in plain text.
export const integrationRoutes = new Elysia({
name: 'integrations',
detail: { tags: ['Integrations'] },
@@ -55,8 +57,7 @@ export const integrationRoutes = new Elysia({
.use(authContext)
.use(guards)
- // The catalog of integrations (LLM providers + tool integrations). The frontend
- // builds the credential form from credentialSchema.
+ // The frontend builds the credential form from credentialSchema.
.get('/projects/:projectKey/integrations/catalog', () => INTEGRATION_CATALOG, {
permission: ['integrations', 'read'],
response: {
@@ -67,17 +68,25 @@ export const integrationRoutes = new Elysia({
},
detail: {
summary: 'List available integrations',
- description: 'List the integration catalog: LLM providers and tool integrations.',
+ description:
+ "List the integration catalog: LLM providers (kind 'llm') and tool integrations " +
+ "(kind 'tool'). A provider key here is what list_provider_models takes.",
+ ...mcpTool('list_integrations'),
},
})
// The models an LLM provider offers, from the models.dev registry. Backs the model
- // select in the agent config UI. Empty when the registry is unavailable.
+ // select in the agent config UI.
.get(
'/projects/:projectKey/integrations/models/:provider',
({ params }) => listModelsForProvider(params.provider),
{
- params: t.Object({ projectKey: t.String(), provider: t.String() }),
+ params: t.Object({
+ projectKey: t.String(),
+ provider: t.String({
+ description: "LLM provider key from list_integrations, e.g. 'anthropic'.",
+ }),
+ }),
permission: ['integrations', 'read'],
response: {
200: t.Array(ProviderModelResponse),
@@ -87,7 +96,11 @@ export const integrationRoutes = new Elysia({
},
detail: {
summary: "List a provider's models",
- description: 'List the models an LLM provider offers.',
+ description:
+ 'List the models an LLM provider offers. An id here is what the model field on ' +
+ 'create_ai_agent / update_ai_agent takes. Empty when the model registry is unreachable.',
+ // The list comes from models.dev, the one route here that reads outside the tracker.
+ ...mcpTool('list_provider_models', { openWorldHint: true }),
},
},
)
@@ -102,7 +115,11 @@ export const integrationRoutes = new Elysia({
},
detail: {
summary: 'List credentials',
- description: "List a project's integration credentials (secrets redacted).",
+ description:
+ "List a project's integration credentials, secrets redacted. The id of a credential " +
+ 'on an LLM provider is what modelCredentialId on create_ai_agent / update_ai_agent takes. ' +
+ 'A credential is added in the UI, not here.',
+ ...mcpTool('list_integration_credentials'),
},
})