> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neptune.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# How It Works

> Learn how Neptune uses MCP to deploy your apps through conversation

Neptune is designed to be the simplest path from code to cloud. Here's how it works under the hood.

## The Neptune Model

**1. You ask your AI assistant to deploy**

Just say "Deploy this app to Neptune" - your AI assistant handles the rest.

**2. Neptune generates your configuration**

Your AI creates an optimized Dockerfile (if needed) and a `neptune.json` configuration based on your project.

**3. Resources are provisioned**

Storage buckets, secrets, and databases are created automatically in the cloud.

**4. Your app is deployed**

Neptune builds your container image, pushes it to a private registry, and deploys it.

**5. You get a public IP**

Your app is live and connected to all your resources.

## The MCP Connection

Neptune uses the **[Model Context Protocol (MCP)](https://modelcontextprotocol.io/)** to connect with your AI coding assistant. MCP is an [open standard](https://github.com/modelcontextprotocol) created by Anthropic that lets AI tools interact with external services.

When you install the Neptune MCP, your AI assistant gains access to tools that can:

* **Authenticate** you with Neptune via GitHub OAuth
* **Generate** Dockerfiles optimized for your project
* **Create** `neptune.json` configurations automatically
* **Provision** cloud resources (storage buckets, secrets, databases)
* **Build and deploy** your application
* **Monitor** deployment status and retrieve logs

This means you can manage your entire deployment lifecycle through natural conversation.

> [!TIP]
>
> Learn more about MCP: [Official Documentation](https://modelcontextprotocol.io/introduction) · [GitHub](https://github.com/modelcontextprotocol) · [Anthropic Announcement](https://www.anthropic.com/news/model-context-protocol)

## Configuration

Neptune uses a `neptune.json` file to define your project. Your AI assistant creates and manages this automatically:

```json neptune.json theme={"dark"}
{
  "kind": "Service",
  "name": "my-app",
  "resources": [
    {
      "kind": "StorageBucket",
      "name": "uploads"
    },
    {
      "kind": "Secret",
      "name": "API_KEY"
    },
    {
      "kind": "Database",
      "name": "my-app-db"
    }
  ]
}
```

You can also specify compute resources and port mappings:

```json neptune.json theme={"dark"}
{
  "kind": "Service",
  "name": "my-app",
  "cpu": "512",
  "memory": "1024",
  "port_mappings": [
    { "container_port": 3000, "host_port": 8080 }
  ]
}
```

## How Resources Work

When Neptune provisions resources, it creates them with unique physical names for global uniqueness. Your AI assistant receives these names and can use them when writing code for you.

| Resource | What Neptune Creates | How You Access It |
| - | - | - |
| StorageBucket | S3 bucket (e.g., `neptune-abc123-uploads`) | `boto3.client("s3")` with the physical bucket name |
| Secret | AWS Secrets Manager secret (e.g., `neptune-abc123-API_KEY`) | `boto3.client("secretsmanager")` with the physical secret name |
| Database | Managed Postgres database | Read the injected environment variable (e.g., `DATABASE_URL_MY_APP_DB`) |

All IAM permissions are pre-configured, so you can use standard AWS SDKs like `boto3` without any credential setup.

## Security

* **Authentication**: GitHub OAuth - no separate Neptune account needed
* **Secrets**: Encrypted at rest in AWS Secrets Manager
* **Network**: All traffic is encrypted with TLS
* **Isolation**: Each project runs in its own isolated environment
* **IAM**: Services only have access to their own resources


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.