Custom GitHub Copilot Agents with Neo4j MCP Cypher Server

This repository demonstrates how to set up custom GitHub Copilot agents that integrate with the Neo4j MCP Cypher Server.

Specifically, this showcases a custom agent that automatically generates high-quality Python Neo4j client libraries with best practices including:

• Pydantic models for type safety
• Repository pattern for clean query organization
• Parameterized Cypher queries to prevent injection attacks
• Integration tests using testcontainers
• Modern Python packaging with pyproject.toml

Important: This repository contains example agent configurations and documentation only. The actual custom agents are deployed in the organization-level neo4j-partners/.github-private repository, where they are available across all repositories in the organization.

This setup was created in the neo4j-partners organization where I had administrator privileges. Organization administrator privileges are required to create the .github-private repository and configure organization-level custom agents with MCP server integrations.

Testing MCP Servers Directly

Before creating custom agents, it can be useful to first test the Neo4j MCP Cypher Server directly to ensure it's working correctly. This allows you to verify connectivity and functionality independently from the agent configuration.

See the GitHub documentation on extending the coding agent with MCP for instructions on how to configure and test MCP servers locally.

This repository includes two example configurations for the Neo4j MCP Cypher Server in sample-mcp-config/:

• neo4j-mcp-docker-config.json - Docker-based MCP server configuration
• neo4j-mcp-local-config.json - Local Python-based MCP server configuration

What are Custom GitHub Copilot Agents?

Custom agents extend GitHub Copilot's capabilities by providing specialized tools and domain-specific knowledge. They can be configured to use external tools, APIs, and MCP servers to perform complex tasks beyond standard code completion.

For more details on custom agents, see:

• GitHub Copilot Custom Agents Documentation
• Awesome Copilot Agents Collection

Critical: Organization-Level Setup for MCP Servers

IMPORTANT: If your agent uses MCP servers, it MUST be created at the organization level in a private .github-private repository.

Individual repository-level agents cannot access MCP servers and will not work. This repository does not contain the actual agents - they must be created in your organization's .github-private repository.

See the official GitHub documentation on creating custom agents for detailed setup instructions.

Prerequisites

1. Create a .github-private repository in your organization first. This is a special private repository that GitHub uses for organization-level configurations. See the GitHub documentation on adding a member-only organization profile README for instructions on creating this repository.

2. Organization administrator privileges are required to create and configure the .github-private repository

3. Access to organization-level settings for environment variables and secrets

Repository Structure

Your organization should have a .github-private repository with the following structure:

<your-org>/.github-private/
└── copilot/
    └── agents/
        ├── your-agent-1.md
        └── your-agent-2.md

Organization and enterprise owners can create custom agents in a .github-private repository that are available across all repositories within their organization or enterprise.

Example Agents

This repository includes two example agents that demonstrate different approaches to running the Neo4j MCP Cypher Server:

1. Docker-Based Agent

See org-setup-files/agents/neo4j-docker-client-generator.md

This agent runs the Neo4j MCP Cypher Server inside a Docker container.

2. Python Direct Agent

See org-setup-files/agents/neo4j-local-client-generator.md

This agent runs the Neo4j MCP Cypher Server directly as a Python command.

Agent File Layout

Each agent definition follows this structure:

---
name: agent-name
description: Brief description of what the agent does
tools: ['read', 'edit', 'search', 'shell', 'mcp-server-name/*']
mcp-servers:
  server-name:
    type: 'local'
    command: 'command-to-run'
    args: ['arg1', 'arg2']
    env:
      VAR_NAME: '${ENVIRONMENT_VARIABLE}'
    tools: ["*"]
---

# Agent Instructions

Your agent's detailed instructions go here...

Setup Overview

Setting up custom agents with MCP servers involves two distinct parts:

Part 1: Organization-Level Agent Configuration

This is where you define your custom agents and their MCP server integrations. This must be done in your organization's .github-private repository.

What goes here:

• Agent definition files (.md files in copilot/agents/)
• MCP server configuration (command, args, env mappings)
• Tool permissions for the agent

Example: See the agent files in org-setup-files/agents/ for complete examples.

Part 2: Repository-Level Configuration

This is where you configure each individual repository to work with your custom agents.

What's required:

For All Agents:

• Create environment variables in repository settings:
  1. Go to Settings → Environments
  2. Create an environment named copilot
  3. Add your Neo4j connection variables:
     • COPILOT_MCP_NEO4J_URI
     • COPILOT_MCP_NEO4J_USERNAME
     • COPILOT_MCP_NEO4J_PASSWORD
     • COPILOT_MCP_NEO4J_DATABASE

Important: Use the COPILOT_MCP_ prefix for all MCP-related variables.

For Python-Based MCP Server Only:

If you're using an agent that runs the Neo4j MCP Cypher Server directly as a Python command (not Docker), you also need:

• A GitHub Actions workflow to set up the Python environment
• See .github/workflows/copilot-setup-steps.yml for the workflow configuration

This workflow ensures that Python and the required Neo4j MCP Cypher Server packages are available when Copilot agents execute.

Note: The Docker-based agent does NOT require the workflow setup since the MCP server runs inside a container with its own environment.

Testing Your Custom Agent

Once your agent is configured, follow these steps to test it:

1. Create and Assign an Issue to Copilot

Create a new issue in your repository and assign it to Copilot.

Important: You must click away from the assignment dropdown after assigning to Copilot, then return to set the custom agent. The custom agent selection will not be available until you click out first.

2. Monitor Agent Startup

Give the agent a couple of minutes to start up. Once it begins, you'll see "Copilot started work on..." in the issue comments. Click on that link to see the status and logs.

3. Verify MCP Server Connection

Once started, you'll see the agent connect to Neo4j and retrieve the schema, confirming that the MCP server integration is working correctly.

4. View Detailed Debug Logs

You can go to the Actions tab in your repository to see detailed debug logs for each agent run.

Example Output

For a complete example of what the agent generates, see PR #4 which shows a full Python Neo4j client library generated by the custom agent, including models, repository patterns, tests, and documentation.

Summary Checklist

Part 1: Organization-Level Setup

• Create .github-private repository in your organization
• Create agent definition files in .github-private/copilot/agents/
• Define MCP server configuration with proper command, args, and env mapping
• Specify tool permissions for each agent

Part 2: Repository-Level Setup

• Create copilot environment in repository settings
• Add COPILOT_MCP_* environment variables in the copilot environment
• (Python MCP only) Set up .github/workflows/copilot-setup-steps.yml workflow
• Test agent with simple queries before deploying complex workflows

Additional Resources

• MCP Protocol Documentation
• GitHub Copilot Extensions
• Neo4j MCP Server