Agentation MCP Server

Common errors

• Error: listen EADDRINUSE: address already in use :::4747

  cause The default HTTP server port (4747) is already in use by another process on your system.
  fix Change the port using the `--port` option for the CLI (e.g., `agentation-mcp server --port 8080`) or by setting the `AGENTATION_PORT` environment variable if running programmatically.

• Command 'claude mcp add agentation' failed or did not register correctly.

  cause The integration with the `claude` CLI might not have completed successfully, or the `agentation` tool was not registered with Claude Code.
  fix Run `npx agentation-mcp doctor` to diagnose setup issues. If the problem persists, try `npx agentation-mcp init` again to re-run the interactive setup wizard, ensuring Claude Code is running and accessible.

• TypeError: (0, import_agentation_mcp.startServer) is not a function

  cause This error typically indicates that `startServer` is not a named export from the `agentation-mcp` package, or the module format (ESM/CJS) is being mishandled.
  fix Verify the exact export names and module structure by inspecting the package's `index.d.ts` or source code. If the package is ESM-only (likely for Node.js 18+), ensure your consuming project is also configured for ESM (e.g., `"type": "module"` in `package.json`). If `startServer` is a default export, use `import startServer from 'agentation-mcp';`.

Warnings

• gotcha The package primarily emphasizes CLI usage via `npx agentation-mcp server`. While it ships TypeScript types, direct programmatic imports and instantiation of the server are not explicitly documented in the README, requiring users to infer the API based on common Node.js server patterns.
  Fix: Consult the TypeScript declaration files (`.d.ts`) or source code to understand the exact programmatic API if you intend to embed the server rather than use the CLI.
• breaking The package requires Node.js version 18 or greater. Running with older Node.js versions will result in execution errors.
  Fix: Ensure your Node.js environment is version 18.0.0 or higher. Use `nvm use 18` or similar version management tools.
• gotcha The MCP server uses stdio for communication with AI agents. Customizing or proxying this communication requires careful handling of child processes and their standard input/output streams, which is beyond the scope of simple HTTP proxying.
  Fix: When integrating with AI agent runners, ensure that the stdio pipes are correctly established and managed for the `agentation-mcp server` process. Refer to the specific AI agent's documentation (e.g., Claude Code) for integration guidelines.

Install

• npm install agentation-mcp npm
• yarn add agentation-mcp yarn
• pnpm add agentation-mcp pnpm

Imports

• startServer
  wrong:

  const { startServer } = require('agentation-mcp');

  correct:

  import { startServer } from 'agentation-mcp';

  While the primary usage is via the CLI `agentation-mcp server`, the library likely exports a `startServer` function (or similar) for programmatic control, especially since it ships TypeScript types. Avoid CommonJS `require()` as the package targets Node.js 18+ and is likely ESM-first.
• ServerOptions
  wrong:

  import { ServerOptions } from 'agentation-mcp';

  correct:

  import { type ServerOptions } from 'agentation-mcp';

  Type-only import for configuration options when programmatically starting the server. Use `type` keyword for clarity and to ensure it's removed during transpilation.
• AgentationMcpCli
  wrong:

  import { AgentationMcpCli } from 'agentation-mcp';

  correct:

  import { runCli } from 'agentation-mcp/cli';

  Although the `agentation-mcp` package is mainly consumed via its `npx agentation-mcp` CLI, if one were to programmatically invoke parts of the CLI functionality or integrate it into a larger application, the CLI entry point might be exposed from a subpath like `agentation-mcp/cli`. This is an assumption based on common Node.js CLI package structures.

Quickstart

Demonstrates how to programmatically start the Agentation MCP server, configuring its port and other options via environment variables, and includes basic signal handling for graceful shutdown.

import { startServer, type ServerOptions } from 'agentation-mcp';

const serverOptions: ServerOptions = {
  port: parseInt(process.env.AGENTATION_PORT ?? '4747', 10),
  mcpOnly: process.env.AGENTATION_MCP_ONLY === 'true',
  httpUrl: process.env.AGENTATION_HTTP_URL,
  // Add other environment variables for webhooks if needed
  // For example, webhookUrl: process.env.AGENTATION_WEBHOOK_URL,
  // webhooks: process.env.AGENTATION_WEBHOOKS?.split(','),
};

async function main() {
  try {
    console.log(`Starting Agentation MCP server with options:`, serverOptions);
    const server = await startServer(serverOptions);
    console.log(`Agentation MCP HTTP server listening on http://localhost:${serverOptions.port}`);
    console.log(`MCP server started (stdio interface for AI agents).`);

    // Keep the process alive, or handle graceful shutdown
    process.on('SIGINT', async () => {
      console.log('Shutting down server...');
      await server.stop(); // Assuming a `stop` method exists
      process.exit(0);
    });
    process.on('SIGTERM', async () => {
      console.log('Shutting down server...');
      await server.stop();
      process.exit(0);
    });

  } catch (error) {
    console.error('Failed to start Agentation MCP server:', error);
    process.exit(1);
  }
}

main();