Connecting your agent

Sandra speaks MCP (Model Context Protocol), the standard way for AI assistants to use external tools. Any MCP-capable client can connect: Claude Code, Claude Desktop, claude.ai, and others.

Status: working. The server answers, and a token is required — an unauthenticated request gets a 401. Twenty tools are advertised: concepts, triplets, entities, types, relations, query, traversal, search and batch.

Claude Code

From your project directory:

claude mcp add sandra --transport http http://127.0.0.1:8090/mcp

Then type /mcp — sandra should appear as connected.

Any client, via configuration

Create .mcp.json in your project:

{
  "mcpServers": {
    "sandra": {
      "type": "http",
      "url": "http://127.0.0.1:8090/mcp"
    }
  }
}

Connecting to a shared instance

A team instance is protected by a token, which goes in an Authorization header:

{
  "mcpServers": {
    "sandra": {
      "type": "http",
      "url": "https://sandra.example.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

Never commit that file. If your team's repository does not already ignore it, exclude it locally without touching the shared .gitignore:

echo ".mcp.json" >> .git/info/exclude

Ask whoever runs the instance for a token. Each one can be revoked individually, so you do not need to share a single password across the team.

Connecting claude.ai

The web client requires HTTPS, which a local instance does not have. Sandra ships a tunnel for this:

docker compose --profile tunnel up -d && docker compose logs tunnel

The log prints a https://….trycloudflare.com URL you can register with claude.ai.

That URL is public while the tunnel runs. Set an authentication token before starting it, and stop the tunnel when you are done.

What you will see when a hosted client connects

When you connect claude.ai (or any client that has never met your server), it will send you to a page on your own Sandra that says which client is asking and what it would be allowed to do. It asks for your Sandra token — the same one from sandra:token create.

Approving does not hand your token over. The client gets its own separate credential, limited to what the page listed, and you can take it back on its own:

php artisan sandra:oauth grants
php artisan sandra:oauth revoke --client=<id>

If you would rather cut off everything at once, revoking the Sandra token you approved with closes every client that was authorised by it.

Checking it works

Ask your assistant to list what types of memory exist. On a fresh instance the answer is "none yet" — which is the correct answer, and confirms the connection.

If it cannot reach Sandra at all, check that the containers are running (docker compose ps) and that http://127.0.0.1:8090/up returns 200.

---

Next: Using memory well.