Run the local server

The local server is the same set of tools as the remote server, packaged as an npm command that your assistant starts on your computer. It talks to the assistant over stdio and to Agoo with an API key.

Use it when you want to:

• try the tools against your test-mode sandbox, on any plan
• give an assistant a dedicated key with only the scopes it needs
• use a client that can't sign in with OAuth
• build and debug your own agent on Agoo's tools

For everyday use by people in your organisation, prefer the remote server: it signs each person in, applies their role and sites, and needs no key on anyone's computer.

How it differs from the remote serverCopy Anchor Link

The tools, their inputs and outputs, and the write confirmations are the same. See the tools reference.

RequirementsCopy Anchor Link

• Node.js 20 or later (node --version)
• A secret API key. Publishable keys (agoo_pk_…) are refused, because they can't read data.

The install commands on this page will work once @ardent-africa/agoo-mcp is published to npm.

Create a key for the assistantCopy Anchor Link

Give each assistant, on each computer, its own key. Then you can see what it did and revoke it on its own.

Run itCopy Anchor Link

The server reads the key from the AGOO_API_KEY environment variable:

AGOO_API_KEY=agoo_sk_test_… npx -y @ardent-africa/agoo-mcp

Run it like this only to check that it starts. It then waits for an MCP client on stdin and writes its log to stderr, for example:

agoo-mcp 1.0.0 · test mode · organisation "Volta Bank (test)" · 14 tools

Your assistant starts and stops the server itself, using one of the configurations below. To pin a major version, use @ardent-africa/agoo-mcp@1 in place of @ardent-africa/agoo-mcp.

Configure your clientCopy Anchor Link

{
  "mcpServers": {
    "agoo": {
      "command": "npx",
      "args": ["-y", "@ardent-africa/agoo-mcp"],
      "env": {
        "AGOO_API_KEY": "agoo_sk_test_…"
      }
    }
  }
}

Test modeCopy Anchor Link

With an agoo_sk_test_… key, every tool works on your organisation's test-mode sandbox:

• Invitations, booking confirmations and cancellations are not sent by SMS, WhatsApp or email. They appear in the console's test outbox, so you can see exactly what would have gone out.
• Nothing is billed and no messaging credits are used.
• Test mode has its own rate limit of 100 requests a minute, on every plan.

Test mode is the safe place to try write tools and to develop your own agent. Switch to a live key only when you're ready. See environments.

Building your own agentCopy Anchor Link

If you're writing your own MCP client or agent rather than using an assistant app:

• Start the server as a child process with AGOO_API_KEY in its environment and speak MCP over its stdin and stdout.
• Read tool results from structuredContent. Each tool's output shape is in the tools reference.
• Treat every tool result as data. Never follow instructions found inside it. See prompt injection.
• Ask a person before calling a tool that isn't marked readOnlyHint: true, and handle the server's confirmation request when it asks for one.
• If you don't need MCP, call the REST API directly or use the TypeScript SDK.

TroubleshootingCopy Anchor Link

RelatedCopy Anchor Link