Project Endpoints

Overview

Project endpoints allow you to create and manage projects, assign configurations to projects, and manage user membership within projects. Projects serve as containers that link users with specific MCP configurations.

List All Projects

Retrieve a list of all projects in the system.

curl -X GET "http://localhost:8001/api/v1/projects" \
  -H "Authorization: Bearer ${ADMIN_KEY}"

Response: 200 OK

{
  "message": "Projects retrieved successfully",
  "data": [
    {
      "project_id": "660e8400-e29b-41d4-a716-446655440000",
      "project_name": "development-project",
      "mcp_config_id": "550e8400-e29b-41d4-a716-446655440000",
      "mcp_config_name": "dev-config",
      "users_count": 3,
      "created_at": "2024-01-01T12:00:00.000000"
    },
    {
      "project_id": "770e8400-e29b-41d4-a716-446655440000",
      "project_name": "production-project",
      "mcp_config_id": "880e8400-e29b-41d4-a716-446655440000",
      "mcp_config_name": "prod-config",
      "users_count": 5,
      "created_at": "2024-01-01T12:00:00.000000"
    }
  ],
  "timestamp": "2024-01-01T12:00:00.000000"
}

data

array

Show Project Object

project_id

string

required

Unique identifier for the project

project_name

string

required

Human-readable name of the project

mcp_config_id

string

ID of the assigned MCP configuration

mcp_config_name

string

Name of the assigned configuration

users_count

integer

required

Number of users in this project

created_at

string

required

ISO 8601 timestamp of project creation

Create Project

Create a new project.

curl -X POST "http://localhost:8001/api/v1/projects" \
  -H "Authorization: Bearer ${ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"project_name": "staging-project"}'

project_name

string

required

Name for the new project (must be unique)

Response: 200 OK

{
  "message": "Project created successfully",
  "data": {
    "project_id": "990e8400-e29b-41d4-a716-446655440000",
    "project_name": "staging-project"
  },
  "timestamp": "2024-01-01T12:00:00.000000"
}

Get Project

Retrieve details of a specific project.

curl -X GET "http://localhost:8001/api/v1/projects/{project_identifier}" \
  -H "Authorization: Bearer ${ADMIN_KEY}"

project_identifier

string

required

Project ID or project name

Response: 200 OK

{
  "message": "Project retrieved successfully",
  "data": {
    "project_id": "660e8400-e29b-41d4-a716-446655440000",
    "project_name": "development-project",
    "mcp_config_id": "550e8400-e29b-41d4-a716-446655440000",
    "users": [
      "440e8400-e29b-41d4-a716-446655440000",
      "330e8400-e29b-41d4-a716-446655440000"
    ],
    "created_at": "2024-01-01T12:00:00.000000"
  },
  "timestamp": "2024-01-01T12:00:00.000000"
}

Delete Project

Delete a project and remove all user associations.

Deleting a project will remove all API keys associated with users in this project.

curl -X DELETE "http://localhost:8001/api/v1/projects/{project_identifier}" \
  -H "Authorization: Bearer ${ADMIN_KEY}"

project_identifier

string

required

Project ID or project name

Response: 200 OK

{
  "message": "Project deleted successfully",
  "timestamp": "2024-01-01T12:00:00.000000"
}

Assign Configuration to Project

Assign an MCP configuration to a project.

curl -X POST "http://localhost:8001/api/v1/projects/{project_identifier}/assign-config" \
  -H "Authorization: Bearer ${ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"config_name": "production-config"}'

project_identifier

string

required

Project ID or project name

config_name

string

Configuration name to assign (either config_name or config_id required)

config_id

string

Configuration ID to assign (either config_name or config_id required)

Response: 200 OK

{
  "message": "Configuration assigned to project successfully",
  "timestamp": "2024-01-01T12:00:00.000000"
}

Unassign Configuration from Project

Remove the configuration assignment from a project.

curl -X POST "http://localhost:8001/api/v1/projects/{project_identifier}/unassign-config" \
  -H "Authorization: Bearer ${ADMIN_KEY}"

project_identifier

string

required

Project ID or project name

Response: 200 OK

{
  "message": "Configuration unassigned from project successfully",
  "timestamp": "2024-01-01T12:00:00.000000"
}

Get Project Configuration

Retrieve the full configuration assigned to a project.

curl -X GET "http://localhost:8001/api/v1/projects/{project_identifier}/config" \
  -H "Authorization: Bearer ${ADMIN_KEY}"

project_identifier

string

required

Project ID or project name

Response: 200 OK

{
  "message": "Project configuration retrieved successfully",
  "data": {
    "mcp_config_id": "550e8400-e29b-41d4-a716-446655440000",
    "mcp_config_name": "production-config",
    "mcp_config": [
      {
        "server_name": "github",
        "description": "GitHub MCP Server",
        "config": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-github"]
        }
      }
    ]
  },
  "timestamp": "2024-01-01T12:00:00.000000"
}

List Project Users

Get all users associated with a project.

curl -X GET "http://localhost:8001/api/v1/projects/{project_identifier}/users" \
  -H "Authorization: Bearer ${ADMIN_KEY}"

project_identifier

string

required

Project ID or project name

Response: 200 OK

{
  "message": "Project users retrieved successfully",
  "data": [
    {
      "user_id": "440e8400-e29b-41d4-a716-446655440000",
      "email": "[email protected]",
      "created_at": "2024-01-01T12:00:00.000000"
    },
    {
      "user_id": "330e8400-e29b-41d4-a716-446655440000",
      "email": "[email protected]",
      "created_at": "2024-01-01T12:00:00.000000"
    }
  ],
  "timestamp": "2024-01-01T12:00:00.000000"
}

Add User to Project

Add an existing user to a project.

curl -X POST "http://localhost:8001/api/v1/projects/{project_identifier}/users" \
  -H "Authorization: Bearer ${ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

project_identifier

string

required

Project ID or project name

string

Email address of the user to add (either email or user_id required)

user_id

string

User ID to add (either email or user_id required)

Response: 200 OK

{
  "message": "User added to project successfully",
  "timestamp": "2024-01-01T12:00:00.000000"
}

Remove User from Project

Remove a user from a project.

Removing a user from a project will invalidate all API keys associated with that user and project.

curl -X DELETE "http://localhost:8001/api/v1/projects/{project_identifier}/users/{user_identifier}" \
  -H "Authorization: Bearer ${ADMIN_KEY}"

project_identifier

string

required

Project ID or project name

user_identifier

string

required

User ID or email address

Response: 200 OK

{
  "message": "User removed from project successfully",
  "timestamp": "2024-01-01T12:00:00.000000"
}

Remove All Users from Project

Remove all users from a project.

This will invalidate all API keys for this project.

curl -X DELETE "http://localhost:8001/api/v1/projects/{project_identifier}/users" \
  -H "Authorization: Bearer ${ADMIN_KEY}"

project_identifier

string

required

Project ID or project name

Response: 200 OK

{
  "message": "All users removed from project successfully",
  "timestamp": "2024-01-01T12:00:00.000000"
}

Export Project

Export a project configuration to a JSON file.

curl -X POST "http://localhost:8001/api/v1/projects/{project_identifier}/export" \
  -H "Authorization: Bearer ${ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"output_file": "/path/to/project-export.json"}'

project_identifier

string

required

Project ID or project name

output_file

string

required

Path where the project will be exported

Response: 200 OK

{
  "message": "Project exported successfully",
  "timestamp": "2024-01-01T12:00:00.000000"
}

Search Projects

Search projects by name.

curl -X POST "http://localhost:8001/api/v1/projects/search" \
  -H "Authorization: Bearer ${ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"search_term": "production"}'

search_term

string

required

Search query (matches against project names)

Response: 200 OK

{
  "message": "Search completed successfully",
  "data": [
    {
      "project_id": "770e8400-e29b-41d4-a716-446655440000",
      "project_name": "production-project",
      "users_count": 5,
      "mcp_config_name": "prod-config"
    }
  ],
  "timestamp": "2024-01-01T12:00:00.000000"
}

Complete Workflow Example

Here’s a complete example of setting up a project with users:

#!/bin/bash

ADMIN_KEY="your-admin-api-key"
BASE_URL="http://localhost:8001/api/v1"

# 1. Create a configuration
CONFIG_RESPONSE=$(curl -s -X POST "${BASE_URL}/configs" \
  -H "Authorization: Bearer ${ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"config_name": "team-config"}')

echo "Config created: ${CONFIG_RESPONSE}"

# 2. Add a server to the configuration
curl -X POST "${BASE_URL}/configs/team-config/servers" \
  -H "Authorization: Bearer ${ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "server_name": "github",
    "server_command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "description": "GitHub MCP Server"
  }'

# 3. Create a project
PROJECT_RESPONSE=$(curl -s -X POST "${BASE_URL}/projects" \
  -H "Authorization: Bearer ${ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"project_name": "engineering-team"}')

echo "Project created: ${PROJECT_RESPONSE}"

# 4. Assign config to project
curl -X POST "${BASE_URL}/projects/engineering-team/assign-config" \
  -H "Authorization: Bearer ${ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"config_name": "team-config"}'

# 5. Create users
for email in "[email protected]" "[email protected]" "[email protected]"; do
  curl -X POST "${BASE_URL}/users" \
    -H "Authorization: Bearer ${ADMIN_KEY}" \
    -H "Content-Type: application/json" \
    -d "{\"email\": \"${email}\"}"
  
  # Add user to project
  curl -X POST "${BASE_URL}/projects/engineering-team/users" \
    -H "Authorization: Bearer ${ADMIN_KEY}" \
    -H "Content-Type: application/json" \
    -d "{\"email\": \"${email}\"}"
  
  # Generate API key for user
  curl -X POST "${BASE_URL}/users/${email}/api-keys" \
    -H "Authorization: Bearer ${ADMIN_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"project_name": "engineering-team"}'
done

echo "Project setup complete!"

Next Steps

User Endpoints

Manage users and their details

API Key Endpoints

Generate and manage API keys

Configuration Endpoints

Manage MCP configurations

System Endpoints

System operations

REST API

CLI Reference

Gateway Tools

Plugin API

Overview

List All Projects

Create Project

Get Project

Delete Project

Assign Configuration to Project

Unassign Configuration from Project

Get Project Configuration

List Project Users

Add User to Project

Remove User from Project

Remove All Users from Project

Export Project

Search Projects

Complete Workflow Example

Next Steps

User Endpoints

API Key Endpoints

Configuration Endpoints

System Endpoints

Build docs developers (and LLMs) love

REST API

CLI Reference

Gateway Tools

Plugin API

​Overview

​List All Projects

​Create Project

​Get Project

​Delete Project

​Assign Configuration to Project

​Unassign Configuration from Project

​Get Project Configuration

​List Project Users

​Add User to Project

​Remove User from Project

​Remove All Users from Project

​Export Project

​Search Projects

​Complete Workflow Example

​Next Steps

User Endpoints

API Key Endpoints

Configuration Endpoints

System Endpoints

Build docs developers (and LLMs) love

Overview

List All Projects

Create Project

Get Project

Delete Project

Assign Configuration to Project

Unassign Configuration from Project

Get Project Configuration

List Project Users

Add User to Project

Remove User from Project

Remove All Users from Project

Export Project

Search Projects

Complete Workflow Example

Next Steps