API Integration Tutorial

Learn how to integrate Plugged.in’s powerful API into your applications for programmatic MCP server management, automation, and custom workflows.

Overview

The Plugged.in API provides comprehensive access to all platform features, enabling you to:

Manage MCP servers programmatically
Automate server discovery and installation
Build custom integrations and workflows
Access RAG knowledge bases
Handle notifications and monitoring

Authentication

API Key Generation

Navigate to API Keys

Go to Settings → API Keys in your Plugged.in dashboard

Create New Key

Click “Create API Key” and provide a descriptive name

Copy Key

Copy the generated key immediately - it won’t be shown again

Store Securely

Store the API key in environment variables or a secure vault

Using Your API Key

Include the API key in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://plugged.in/api/servers

Or in JavaScript:

const response = await fetch('https://plugged.in/api/servers', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

Core API Endpoints

MCP Servers

List All Servers

GET /api/servers

Response:

{
  "servers": [
    {
      "uuid": "server-uuid",
      "name": "My MCP Server",
      "type": "STDIO",
      "config": {...},
      "status": "connected"
    }
  ]
}

Create Server

POST /api/servers

Request Body:

{
  "name": "New Server",
  "type": "STDIO",
  "config": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-memory"]
  }
}

Update Server

PUT /api/servers/{uuid}

Request Body:

{
  "name": "Updated Name",
  "config": {
    "command": "node",
    "args": ["server.js"]
  }
}

Delete Server

DELETE /api/servers/{uuid}

Server Discovery

Search Registry

GET /api/registry/search?q=weather

Response:

{
  "results": [
    {
      "name": "weather-server",
      "description": "Get weather information",
      "author": "username",
      "stars": 42,
      "installs": 1337
    }
  ]
}

Install from Registry

POST /api/registry/install

Request Body:

{
  "server_name": "weather-server",
  "profile_uuid": "profile-uuid"
}

Tools and Resources

List Server Tools

GET /api/servers/{uuid}/tools

Response:

{
  "tools": [
    {
      "name": "get_weather",
      "description": "Get current weather",
      "inputSchema": {...}
    }
  ]
}

Execute Tool

POST /api/servers/{uuid}/tools/{tool_name}/execute

Request Body:

{
  "parameters": {
    "location": "New York"
  }
}

Advanced Integration Patterns

Webhook Integration

Set up webhooks for real-time notifications:

// Register webhook
const webhook = await fetch('https://plugged.in/api/webhooks', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://your-app.com/webhook',
    events: ['server.connected', 'server.error', 'tool.executed']
  })
});

Batch Operations

Process multiple operations efficiently:

// Batch create servers
const batchCreate = await fetch('https://plugged.in/api/batch', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    operations: [
      {
        method: 'POST',
        path: '/servers',
        body: { name: 'Server 1', type: 'STDIO', config: {...} }
      },
      {
        method: 'POST',
        path: '/servers',
        body: { name: 'Server 2', type: 'SSE', config: {...} }
      }
    ]
  })
});

Streaming Responses

Handle streaming responses for real-time data:

// SSE connection for live updates
const eventSource = new EventSource(
  'https://plugged.in/api/servers/events?token=YOUR_API_KEY'
);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Server event:', data);
};

eventSource.addEventListener('tool.executed', (event) => {
  const result = JSON.parse(event.data);
  console.log('Tool result:', result);
});

SDK Examples

JavaScript/TypeScript

import { PluggedinClient } from '@pluggedin/sdk';

const client = new PluggedinClient({
  apiKey: process.env.PLUGGEDIN_API_KEY
});

// List servers
const servers = await client.servers.list();

// Create server
const newServer = await client.servers.create({
  name: 'My Server',
  type: 'STDIO',
  config: {
    command: 'npx',
    args: ['-y', '@modelcontextprotocol/server-memory']
  }
});

// Execute tool
const result = await client.servers.executeTool(
  'server-uuid',
  'get_weather',
  { location: 'London' }
);

Python

from pluggedin import PluggedinClient

client = PluggedinClient(api_key="YOUR_API_KEY")

# List servers
servers = client.servers.list()

# Create server
new_server = client.servers.create(
    name="My Server",
    type="STDIO",
    config={
        "command": "python",
        "args": ["server.py"]
    }
)

# Execute tool
result = client.servers.execute_tool(
    server_uuid="server-uuid",
    tool_name="get_weather",
    parameters={"location": "Paris"}
)

Go

package main

import (
    "github.com/pluggedin/go-sdk"
)

func main() {
    client := pluggedin.NewClient("YOUR_API_KEY")

    // List servers
    servers, err := client.Servers.List()
    if err != nil {
        log.Fatal(err)
    }

    // Create server
    server, err := client.Servers.Create(&pluggedin.ServerConfig{
        Name: "My Server",
        Type: "STDIO",
        Config: map[string]interface{}{
            "command": "go",
            "args": []string{"run", "server.go"},
        },
    })

    // Execute tool
    result, err := client.Servers.ExecuteTool(
        "server-uuid",
        "get_weather",
        map[string]interface{}{"location": "Tokyo"},
    )
}

Rate Limiting and Quotas

API rate limits are enforced to ensure fair usage and platform stability.

Rate Limits by Tier

Tier	Requests/Hour	Burst Limit	Concurrent Connections
Free	100	10	2
Pro	1,000	50	10
Business	10,000	200	50
Enterprise	Custom	Custom	Custom

Handling Rate Limits

The API returns rate limit information in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1640995200

Implement exponential backoff for rate limit errors:

async function apiCallWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || Math.pow(2, i);
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      continue;
    }

    return response;
  }
  throw new Error('Max retries exceeded');
}

Error Handling

Common Error Codes

Code	Description	Resolution
400	Bad Request	Check request format and parameters
401	Unauthorized	Verify API key is valid
403	Forbidden	Check permissions for resource
404	Not Found	Verify resource exists
429	Too Many Requests	Implement rate limiting
500	Internal Server Error	Contact support if persists

Error Response Format

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "The 'name' field is required",
    "details": {
      "field": "name",
      "value": null
    }
  }
}

Error Handling Example

try {
  const response = await fetch('https://plugged.in/api/servers', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(serverConfig)
  });

  if (!response.ok) {
    const error = await response.json();

    switch (response.status) {
      case 400:
        console.error('Invalid request:', error.message);
        break;
      case 401:
        console.error('Authentication failed');
        break;
      case 429:
        console.error('Rate limited, retry after:', response.headers.get('Retry-After'));
        break;
      default:
        console.error('API error:', error);
    }
  }

  const data = await response.json();
  return data;
} catch (err) {
  console.error('Network error:', err);
}

Testing Your Integration

Using the API Playground

Test API endpoints directly in the browser:

Visit https://plugged.in/api/playground
Enter your API key
Select an endpoint
Configure parameters
Execute and view response

Postman Collection

Import our Postman collection for easy testing:

{
  "info": {
    "name": "Plugged.in API",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "auth": {
    "type": "bearer",
    "bearer": [
      {
        "key": "token",
        "value": "{{api_key}}"
      }
    ]
  }
}

Mock Server

Use our mock server for development:

# Install mock server
npm install -g @pluggedin/mock-server

# Run mock server
pluggedin-mock --port 3000

# Point your API calls to localhost
API_BASE_URL=http://localhost:3000

Best Practices

Security

Never expose API keys in client-side code
Use environment variables for key storage
Rotate keys regularly
Implement IP whitelisting for production
Use HTTPS for all API calls

Performance

Cache frequently accessed data
Use pagination for large datasets
Implement connection pooling
Batch operations when possible
Use webhooks instead of polling

Reliability

Implement retry logic with exponential backoff
Handle network timeouts gracefully
Log all API interactions
Monitor API usage and errors
Set up alerts for failures

Development

Use versioned API endpoints
Test with mock data first
Implement comprehensive error handling
Document your integration
Keep SDKs updated

Example Applications

Monitoring Dashboard

Build a real-time monitoring dashboard:

// Real-time server status monitoring
class ServerMonitor {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.servers = new Map();
  }

  async start() {
    // Initial load
    const servers = await this.fetchServers();
    servers.forEach(s => this.servers.set(s.uuid, s));

    // Subscribe to updates
    this.subscribeToUpdates();

    // Periodic health checks
    setInterval(() => this.healthCheck(), 30000);
  }

  subscribeToUpdates() {
    const eventSource = new EventSource(
      `https://plugged.in/api/events?token=${this.apiKey}`
    );

    eventSource.onmessage = (event) => {
      const update = JSON.parse(event.data);
      this.handleUpdate(update);
    };
  }

  async healthCheck() {
    for (const [uuid, server] of this.servers) {
      const health = await this.checkServerHealth(uuid);
      this.updateServerStatus(uuid, health);
    }
  }
}

Automation Workflow

Create an automation workflow:

// Automated server provisioning
class ServerProvisioner {
  async provisionForUser(userId, template) {
    // Create project
    const project = await this.createProject(userId);

    // Install servers from template
    for (const serverConfig of template.servers) {
      await this.installServer(project.uuid, serverConfig);
    }

    // Configure integrations
    await this.setupIntegrations(project.uuid, template.integrations);

    // Send notification
    await this.notifyUser(userId, project);

    return project;
  }
}

​API Integration Tutorial

​Overview

​Authentication

​API Key Generation

​Using Your API Key

​Core API Endpoints

​MCP Servers

​List All Servers

​Create Server

​Update Server

​Delete Server

​Server Discovery

​Search Registry

​Install from Registry

​Tools and Resources

​List Server Tools

​Execute Tool

​Advanced Integration Patterns

​Webhook Integration

​Batch Operations

​Streaming Responses

​SDK Examples

​JavaScript/TypeScript

​Python

​Go

​Rate Limiting and Quotas

​Rate Limits by Tier

​Handling Rate Limits

​Error Handling

​Common Error Codes

​Error Response Format

​Error Handling Example

​Testing Your Integration

​Using the API Playground

​Postman Collection

​Mock Server

​Best Practices

​Example Applications

​Monitoring Dashboard

​Automation Workflow

​Next Steps

RAG Knowledge Base

Team Collaboration

​Additional Resources

API Integration Tutorial

Overview

Authentication

API Key Generation

Using Your API Key

Core API Endpoints

MCP Servers

List All Servers

Create Server

Update Server

Delete Server

Server Discovery

Search Registry

Install from Registry

Tools and Resources

List Server Tools

Execute Tool

Advanced Integration Patterns

Webhook Integration

Batch Operations

Streaming Responses

SDK Examples

JavaScript/TypeScript

Python

Go

Rate Limiting and Quotas

Rate Limits by Tier

Handling Rate Limits

Error Handling

Common Error Codes

Error Response Format

Error Handling Example

Testing Your Integration

Using the API Playground

Postman Collection

Mock Server

Best Practices

Example Applications

Monitoring Dashboard

Automation Workflow

Next Steps

Additional Resources