Neo4j Aura Provisioning Skill

> **Status: Draft / WIP**

# neo4j-aura-provisioning-skill

Guides agents through programmatic provisioning of Neo4j Aura instances: aura-cli, Aura REST API, instance lifecycle management, and CI/CD credential handling.

**Install:**
```bash
npx skills add https://github.com/neo4j-contrib/neo4j-skills --skill neo4j-aura-provisioning-skill
```

Or paste this link into your coding assistant:
https://github.com/neo4j-contrib/neo4j-skills/tree/main/neo4j-aura-provisioning-skill


# Aura Agent (No-Code AI Agent)

No/low-code platform in the Aura Console for building AI agents that query AuraDB with natural language.

## When to Use

Use Aura Agent for: retrieval assistants over graph data without app code, natural language queries from the console, prototyping agent behavior.

Use LangChain/LangGraph/etc. for: custom orchestration, multi-agent coordination, production deployment outside Aura console.

## Prerequisites

In organization settings, both must be enabled:
- **Generative AI assistance**
- **Aura Agent**

**Tool authentication** must be enabled for the project (default ON for orgs created after May 2025; enable manually for older orgs).

## How It Works

Agent loop: interpret user input → plan tools → execute tools (read-only graph queries) → generate response.

## Tool Types

| Tool | Description | Use when |
|---|---|---|
| **Cypher Template** | Parameterized Cypher — agent extracts params from question | Known, repeatable query patterns |
| **Similarity Search** | Vector search using a vector index + embeddings | Semantic similarity ("products similar to X") |
| **Text2Cypher** | LLM generates Cypher at runtime from natural language | Ad-hoc questions not covered by templates |

All tools are **read-only**. Agent cannot write to the database.

Similarity Search requires: vector index on AuraDB instance + embeddings stored on nodes.

## MCP Endpoint

Agents can be exposed as MCP servers for use with external clients (Cursor, Claude Desktop, etc.):

1. Select agent → `...` menu → Configure
2. Under Access, select **External**
3. Enable **MCP server** toggle → click "Update agent"
4. Copy MCP endpoint: `...` menu → "Copy MCP server endpoint"

MCP config for Cursor (`~/.cursor/mcp.json`):
```json
{
  "mcpServers": {
    "my-aura-agent": {
      "url": "<your-mcp-url>",
      "transport": "http"
    }
  }
}
```

Authentication: OAuth2 via Aura console. First connection prompts browser login → "Continue with Neo4j Aura" → Accept.

Restart client after adding MCP endpoint (Cursor, Claude Desktop, etc.).

For Claude Desktop and other clients: see https://neo4j.com/docs/aura/aura-agent/


# Aura Monitoring and Metrics

## Accessing Metrics

Quick view: expand **Metrics** section at bottom of instance card (shows CPU, Storage, Query Rate for last 24h).
Full dashboard: instance card → "View all metrics" button, or Operations → Metrics in left menu.

## Metrics Dashboard Tabs

**Resources tab:**
- CPU Usage — min/max/avg % of CPU capacity
- Storage — % disk used
- Out of Memory Errors — count; **critical metric**, monitor closely

**Instance tab:**
- Heap — min/max/avg heap memory for query execution
- Page Cache — % time data found in memory (higher = better; low = disk reads hurting performance)
- Page Cache Evictions — times/min data swapped out; frequent spikes = page cache too small
- Bolt Connections — active Cypher transaction connections
- Garbage Collection — % time freeing memory; high = memory strain

**Database tab:**
- Store Size, Query Metrics, Transaction counts, Checkpoint/Replan stats

## External Monitoring (Prometheus)

Aura exposes a Prometheus-compatible endpoint per project:

```
https://customer-metrics-api.neo4j.io/api/v1/<project-id>/<metrics-id>/metrics
```

Authentication: OAuth2 with Client ID + Client Secret from Metrics Integration settings.
Token URL: `https://api.neo4j.io/oauth/token`

Prometheus config:
```yaml
- job_name: 'aura-metrics'
  scrape_timeout: 30s
  metrics_path: '/api/v1/<project-id>/<m