Model Context Protocol (MCP)

You run a focused MCP (Model Context Protocol) server that exposes a toolset for an AI assistant, enabling AI apps to access and control AVA-like capabilities through a well-defined MCP interface. This server is designed to be started locally and then consumed by MCP clients to perform tasks via the AVA‑style workflow.

How to use

To use this MCP server, you connect your MCP client to the AVA MCP endpoint. The client sends requests to the server to access AVA’s capabilities, such as updating personal details, managing preferences, and handling task instructions. The server runs the AVA MCP entry point locally, and the client interacts with it through the standardized MCP communication patterns. You will typically start the server in a development mode, then point your MCP client to the local process to begin issuing commands and receiving results.

How to install

Prerequisites: you need a runtime to execute the MCP server and a helper runner to start it. The example uses a tool called UV to manage the MCP server process.

# Mac/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Test the server in development mode using the MCP runner. This starts the server with the AVA MCP entry point so you can verify it is working before integration with a client.

uv run mcp dev mcp-server-example.py

Add the server configuration to your MCP client configuration so it can connect to the local AVA MCP server. The example shows how to configure the AVA MCP entry with the path to your UV runtime and the script that starts the server.

{
  "mcpServers": {
    "AVA": {
      "command": "/Users/sh Shawhin/.local/bin/uv", # replace with global path to your uv installation
      "args": [
        "--directory",
        "/Users/shawhin/Documents/_code/_stv/sandbox/ava-mcp/", # replace with global path to repo
        "run",
        "mcp-server-example.py"
      ]
    }
  }
}

Additional setup and runtime details

Environment setup for AVA-like behavior and access control relies on authentication and configuration stored in a project directory. You can customize prompts and behavior by editing employee-facing configuration files in your project, such as personal prompts that guide how AVA should respond and handle tasks.

Environment variables play a key role in authorizing and configuring access to external services. Create a local environment file in your project root and define the required variables. For example, you may store user identity, credentials, and tokens, then reference them from your running server.

Environment and OAuth setup for external access

You may need to authorize the MCP server to access your Google account for specific tasks. The process involves creating OAuth credentials in a Google Cloud project, setting up Gmail access scopes, and performing a one-time sign-in flow to obtain a token that the server can reuse.

Create your Google OAuth credentials, download them, and place them in your project under a path you control. Then run an authentication helper to complete the OAuth flow and store the token for subsequent requests.

Security notes

Do not commit sensitive credentials or tokens to version control. Keep your environment files secure and add them to your ignore lists so they are not shared in code repositories.