AJERISDocs

Connect your MCP server

Step-by-step guide to connecting any Model Context Protocol server to your Ajeris agent.

Connect Your MCP Server to Ajeris

Ajeris can connect to any MCP (Model Context Protocol) server, giving your personal agent access to tools you've already built or installed. If you have an MCP server, yours, your company's, or one from the community, you can plug it in and talk to it via voice or text.

What is an MCP server?

An MCP server is a program that exposes tools to AI agents. Instead of building every integration from scratch, MCP lets you package tools (API calls, database queries, file operations, etc.) as a server that any MCP-compatible agent can connect to.

Examples of things people build as MCP servers:

  • Company dashboards (Salesforce pipeline, Sentry errors, analytics)
  • Developer tools (GitHub PRs, Linear tickets, database queries)
  • Home automation (custom smart home APIs)
  • Industry-specific tools (financial data, healthcare systems, etc.)

Ajeris supports over 11,800 community MCP servers plus any custom server you build yourself.

Two ways to connect

Option 1: Local server (stdio)

Your MCP server runs as a local program on the same machine as the Ajeris agent. This is the most common setup for development and personal use.

You provide:

  • Label: A name for the server (e.g., "My Company Tools")
  • Command: How to start the server (e.g., node, python, npx)
  • Args: The path to the server and any CLI arguments
  • Environment variables: API keys, tokens, database URLs, whatever the server needs to connect to your services

Example, connecting a custom company MCP server:

npx tsx scripts/seed-custom-mcp.ts \
  --label "Company Tools" \
  --transport stdio \
  --command node \
  --args /path/to/your/mcp-server/dist/index.js \
  --env-file /path/to/your/.env

Example, connecting a community GitHub MCP server:

npx tsx scripts/seed-custom-mcp.ts \
  --label "GitHub" \
  --transport stdio \
  --command npx \
  --args @modelcontextprotocol/server-github \
  --env-file github-env.txt

Where github-env.txt contains:

GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here

Option 2: Remote server (Streamable HTTP)

Your MCP server is hosted remotely (on Railway, Fly.io, AWS, etc.) and accessible via HTTPS. Ajeris connects over the network.

You provide:

  • Label: A name for the server
  • URL: The HTTPS endpoint (e.g., https://api.mycompany.com/mcp)
  • Headers: Authentication headers (e.g., Bearer token)

Example, connecting a remote server:

npx tsx scripts/seed-custom-mcp.ts \
  --label "Company API" \
  --transport http \
  --url https://api.mycompany.com/mcp \
  --header "Authorization=Bearer sk-live-your-token"

What happens after you connect

  1. Your agent gains new tools. The next time you ask your agent a question, it can see and use all the tools from your MCP server alongside its built-in tools (Gmail, Calendar, Spotify, Slack, etc.).

  2. One conversation, all tools. You don't switch between "personal mode" and "work mode." Just talk naturally:

    • "What's in my email?" → uses built-in Gmail tools
    • "Any Sentry errors today?" → uses your company MCP server
    • "Play John Legend and check my calendar" → uses Spotify + Calendar

    All in the same conversation, same agent, any surface (voice or text).

  3. Cross-surface delivery. If your company MCP server returns data that's better viewed on screen (error stacktraces, pipeline tables, charts), the agent automatically texts it to your phone instead of reading it aloud on voice.

Security

  • Your credentials are encrypted in the database. API keys, tokens, and other secrets are never stored in plaintext.

  • Servers are isolated. Each MCP server runs in its own subprocess with only the environment variables you configured. It cannot access the agent's own credentials or other servers' credentials.

  • You control what's connected. You can enable or disable servers at any time. Disabled servers are not loaded.

  • Tool visibility. When you first connect a server, Ajeris shows you the full list of tools it provides so you know exactly what you're giving the agent access to.

Finding MCP servers

If you don't have your own MCP server, you can find community servers at:

  • Docker MCP Catalog: 300+ verified servers, install from Docker Desktop or via docker mcp CLI
  • MCP Registry: registry.modelcontextprotocol.io, official cross-company catalog
  • PulseMCP: pulsemcp.com/servers, 11,800+ community servers indexed and searchable
  • Smithery: smithery.ai, 2,200+ servers with automated install guides

Popular servers include GitHub, Notion, Linear, PostgreSQL, MongoDB, Brave Search, Stripe, Datadog, and many more.

Troubleshooting

"The agent doesn't seem to use my MCP tools"

  • Make sure the server is enabled in the database
  • Restart the agent after adding a new server
  • Check the agent log for errors during MCP server startup
  • If using stdio, make sure the command runs from the correct directory (use bash -c "cd /path && command" if needed)

"The server fails to start"

  • Check that all required environment variables are set
  • For Node.js servers: make sure dependencies are installed (npm install in the server's directory)
  • For Python servers: make sure the virtualenv is activated
  • Check for ESM/CJS module conflicts (if the server uses import syntax, the package.json needs "type": "module")

"Too many tools slow down responses"

  • Each MCP server's tools consume context tokens on every turn. A server with 70 tools adds ~15,000 tokens of overhead.
  • Consider disabling servers you don't use frequently.
  • Future versions will support selective tool loading.

For developers: building your own MCP server

If you want to build a custom MCP server for your team or company:

  1. Use the official MCP SDK: @modelcontextprotocol/sdk (TypeScript) or mcp (Python)
  2. Define your tools with clear names and descriptions
  3. Use stdio transport for local development
  4. Package as an npm module or Docker image for distribution
  5. Document required environment variables

Resources:

  • MCP Specification: modelcontextprotocol.io/specification
  • TypeScript SDK: github.com/modelcontextprotocol/typescript-sdk
  • Python SDK: github.com/modelcontextprotocol/python-sdk
  • Example servers: github.com/modelcontextprotocol/servers

Coming soon

  • Settings UI: Connect MCP servers from a web interface instead of the command line (no code required)
  • OAuth integration: "Connect GitHub" / "Connect Linear" buttons that handle authentication automatically
  • MCP marketplace: Browse and install community servers with one click during onboarding
  • Tool filtering: Choose which tools from a server to enable, reducing context overhead