Sphere

Deployment Overview

Deploy Sphere's MCP server in your AWS environment using Terraform

Self-hosted deployments run entirely within your AWS account, providing complete data isolation and compliance with air-gapped or GovCloud requirements.

Step 1

Get Access

Contact Sphere to receive terraform module access and your license key.

Step 2

Configure

Fill out terraform.tfvars with your VPC and network settings.

Step 3

Deploy

Run terraform apply to provision all infrastructure.

Step 4

Connect

Use the NLB endpoint to connect your AI applications.

Terraform Configuration

Configure your deployment in terraform.tfvars

Copy terraform.tfvars.example to terraform.tfvars and configure the following required variables:

Required Variables

Variable	Description	Example
vpc_id	Your existing VPC ID	"vpc-0abc123def456"
database_subnet_ids	Private subnets for Aurora (2+ AZs)	["subnet-aaa", "subnet-bbb"]
app_subnet_ids	Private subnets for ECS tasks	["subnet-ccc", "subnet-ddd"]
content_api_endpoint_service	Sphere Content API PrivateLink endpoint (provided by Sphere)	"com.amazonaws.vpce.us-gov-west-1.vpce-svc-..."
mcp_server_port	Port for MCP server (default: 8002)	8002

Example terraform.tfvars

Minimal configuration required. Database snapshot and images are pre-configured.

# Network Configuration (required)
vpc_id              = "vpc-0abc123def456"
database_subnet_ids = ["subnet-db1", "subnet-db2"]
app_subnet_ids      = ["subnet-app1", "subnet-app2"]

# Sphere Content API (PrivateLink - provided by Sphere during onboarding)
content_api_endpoint_service = "com.amazonaws.vpce.us-gov-west-1.vpce-svc-0930f5e94d9c36819"
mcp_server_port = 8002

Deploy

# Initialize terraform
terraform init

# Review the plan
terraform plan

# Deploy infrastructure
terraform apply

# After deployment, get the MCP endpoint:
terraform output nlb_dns_name

Security & Permissions

IAM permissions and security features

Required IAM Permissions

The user or role running Terraform needs these permissions:

Compute & Networking

• EC2 (instances, security groups, VPC endpoints)
• ECS (clusters, services, task definitions)
• Elastic Load Balancing (NLB, target groups)
• Auto Scaling (for ECS capacity)

Data & Storage

• RDS (Aurora clusters, snapshots)
• S3 (for logs and delta sync)
• Secrets Manager (database credentials)
• KMS (encryption keys)

Management

• IAM (roles, policies for ECS tasks)
• CloudWatch (logs, metrics, alarms)
• EventBridge (for delta sync scheduling)
• Lambda (for delta sync processing)

Optional Services

• Bedrock (if using managed LLM)
• CodeBuild (for image sync)
• ACM (for internal HTTPS)

Resources Created by Terraform

Resource	Purpose
Aurora PostgreSQL Cluster	Stores pre-computed vector data (restored from snapshot)
ECS Cluster + Service	Runs inference API and model server containers on GPU instances
Network Load Balancer	Provides stable endpoint for MCP connections
Security Groups	Controls network access between components
VPC Endpoints	Private connectivity to AWS services (ECR, S3, etc.)
IAM Roles	Task execution and instance roles with least-privilege
Secrets Manager Secret	Stores database credentials securely
CloudWatch Log Groups	Centralized logging for debugging
Lambda + EventBridge (optional)	Delta sync for weekly content updates

Security Features

• Encryption at Rest: All data encrypted with KMS (SOC 2 compliant)
• Encryption in Transit: TLS for all network communication
• Network Isolation: Private subnets with no public IPs
• VPC Endpoints: No internet egress required for AWS services
• Deletion Protection: Enabled by default for Aurora
• Audit Logging: VPC Flow Logs and CloudWatch

Available MCP Tools

Tools exposed by the self-hosted MCP server

searchResearch topics using Sphere's knowledge base

Performs semantic search across licensed research content, returning relevant passages with full attribution.

Parameters:

query	required	Search query (max 50,000 chars)
number_of_c3s	optional	Number of results (1-100, default: 10)
include_timing	optional	Include timing info (default: false)
reduce	optional	Extract key points with LLM (default: true)

Example:

{
  "name": "search",
  "arguments": {
    "query": "effects of nanostructured surface modifications on titanium alloy fatigue",
    "number_of_c3s": 5,
    "reduce": true
  }
}

fetchRetrieve a specific content chunk by ID

Retrieves the full content of a specific chunk when you have its ID from a previous search result.

Parameters:

required

The unique chunk ID to fetch

Example:

{
  "name": "fetch",
  "arguments": {
    "id": "chunk_abc123def456"
  }
}

search_linksFind relevant web links from curated sources

Searches for relevant links from trusted academic and research sources like arXiv, PubMed, and more.

Parameters:

query	required	Search query
number_of_results	optional	Number of links (default: 10)
domain_filter	optional	Filter by domain (e.g., "arxiv.org")
matching_threshold	optional	Similarity threshold 0-1

Example:

{
  "name": "search_links",
  "arguments": {
    "query": "transformer architecture attention mechanisms",
    "number_of_results": 5,
    "domain_filter": "arxiv.org"
  }
}

lucieCreative hypothesis generation & brainstorming

Generates creative hypotheses and research directions by connecting concepts across different domains in the knowledge base.

Parameters:

query	required	Topic for creative exploration
wildness	required	0 = conservative, 1 = moderate, 2 = maximum creativity

Example:

{
  "name": "lucie",
  "arguments": {
    "query": "novel applications of graphene in battery technology",
    "wildness": 1
  }
}

list_toolsDiscover all available tools and specifications

Returns the full MCP tool specification for all available tools. No parameters required.

search_localSearch customer-ingested documents

Vector similarity search against customer-ingested documents only. Does not search Sphere's curated knowledge base.

Parameters:

query	required	Search query text
number_of_results	optional	Results to return (default: 5, max: 50)
include_timing	optional	Include timing info (default: false)

Example:

{
  "name": "search_local",
  "arguments": {
    "query": "thermal management in satellite systems",
    "number_of_results": 10
  }
}

Managing customer documents (uploading from S3, monitoring jobs, cleanup, cancellation) is documented separately on the Customer Ingestion Documentation page. Both MCP tools and equivalent REST endpoints are described there.

Verify Your Deployment

After deployment, test the MCP endpoint:

# Get your NLB endpoint
NLB_DNS=$(terraform output -raw nlb_dns_name)

# Health check
curl http://$NLB_DNS:8002/health

# Test search tool
curl -X POST http://$NLB_DNS:8002/mcp/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_LICENSE_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search",
      "arguments": {"query": "machine learning", "number_of_c3s": 3}
    }
  }'

Need Help?

Get support for self-hosted deployment

Contact Support Contact Sales for Self-Hosted