Skip to main content
A connector links your agent or gateway to external services. No code required—Noorle handles authentication, error handling, and tool discovery.

​
Connector Types

​
1. REST API Connector

Connect to any REST API. Noorle translates HTTP endpoints into MCP tools. Supported authentication:
  • Bearer token
  • API key (in headers)
  • OAuth 2.1
Example: Shopify 
{
  "type": "rest",
  "name": "Shopify Store",
  "base_url": "https://store.myshopify.com/api/2024-01",
  "operations": [
    {
      "name": "list_orders",
      "method": "GET",
      "path": "/orders.json",
      "description": "Get all orders"
    },
    {
      "name": "create_order",
      "method": "POST",
      "path": "/orders.json",
      "description": "Create a new order",
      "request_body": {
        "type": "object",
        "properties": {
          "email": { "type": "string" },
          "line_items": { "type": "array" }
        }
      }
    }
  ],
  "auth": {
    "type": "bearer",
    "token": "encrypted-token"
  }
}
Features:
  • OpenAPI import (auto-discover endpoints from spec file)
  • Manual operation definition
  • Custom headers per request
  • Request transformation
  • Response parsing
When to use:
  • Integrate existing REST APIs
  • No custom logic needed
  • Just need to call endpoints

​
2. MCP Registry Connector

Use pre-built MCP servers from the community registry. Available servers:
  • Airtable - Access Airtable bases and tables
  • GitHub - Query repos, issues, PRs
  • HubSpot - CRM data access
  • Slack - Send messages, manage channels
  • Linear - Project management
  • Notion - Query databases and pages
Example: GitHub 
{
  "type": "mcp_registry",
  "registry_name": "io.github.model-context-protocol/github",
  "version": "1.0.0",
  "auth": {
    "type": "bearer",
    "token": "encrypted-github-token"
  }
}
Discovery:
  1. Search MCP registry for “github”
  2. Select version and confirm
  3. Provide authentication
  4. Tools are automatically discovered
When to use:
  • Service has official MCP server
  • Want maintained, tested integrations
  • Prefer standardized interface

​
3. Custom MCP Connector

Connect to your own MCP server. Example: Internal Analytics Server 
{
  "type": "custom",
  "name": "Analytics Backend",
  "transport": {
    "type": "http",
    "url": "https://analytics.internal.example.com/mcp",
    "headers": [
      {
        "name": "X-API-Key",
        "value": "encrypted-key"
      }
    ]
  }
}
Transports:
  • HTTP/HTTPS (POST to endpoint)
  • Server-Sent Events (SSE)
  • WebSocket (for real-time)
When to use:
  • Expose internal MCP server
  • Have your own custom MCP implementation
  • Want full control over protocol

​
Creating a Connector

​
Via OpenAPI Import (REST)

Fastest way for REST APIs:
  1. Get OpenAPI spec (usually at /openapi.json or /v1/spec)
  2. Console → Gateways → Add Capability → Connector
  3. Select “REST API”
  4. Paste OpenAPI URL or file
  5. Noorle auto-discovers endpoints
  6. Configure authentication
  7. Choose which operations to expose
  8. Save
Example OpenAPI URL: 
https://api.example.com/v1/openapi.json

​
Manual REST Definition

If OpenAPI not available: 
{
  "operations": [
    {
      "name": "get_user",
      "method": "GET",
      "path": "/users/{user_id}",
      "description": "Get user by ID",
      "parameters": [
        {
          "name": "user_id",
          "location": "path",
          "type": "string",
          "required": true
        }
      ]
    },
    {
      "name": "update_user",
      "method": "PUT",
      "path": "/users/{user_id}",
      "request_body": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "email": { "type": "string" }
        }
      }
    }
  ]
}

​
Via MCP Registry

  1. Console → Add Capability → Connector
  2. Select “MCP Registry”
  3. Search for service name
  4. Select version
  5. Configure authentication
  6. Save

​
Via Custom MCP

  1. Ensure your MCP server is running
  2. Console → Add Capability → Connector
  3. Select “Custom MCP”
  4. Enter transport URL
  5. Configure authentication
  6. Test connection
  7. Save

​
Authentication

​
Bearer Token

Simple token in Authorization header. 
curl -H "Authorization: Bearer sk-1234567890" https://api.example.com/users
Setup:
  1. Get token from service (usually account settings)
  2. Noorle encrypts and stores it
  3. Automatically included in requests

​
API Key

Token in custom header (varies by service). 
curl -H "X-API-Key: sk-1234567890" https://api.example.com/users
Variations:
  • X-API-Key header
  • API-Key header
  • Authorization: ApiKey sk-123
Noorle detects and configures automatically.

​
OAuth 2.1

For services that require OAuth: 
{
  "type": "oauth2",
  "provider": {
    "type": "custom",
    "authorization_url": "https://auth.example.com/oauth/authorize",
    "token_url": "https://auth.example.com/oauth/token"
  },
  "client_id": "public-id",
  "client_secret": "encrypted-secret",
  "scopes": ["read:users", "write:data"]
}
Flow:
  1. Noorle exchanges code for access token
  2. Stores token encrypted
  3. Auto-refreshes when expired
  4. All requests include access token

​
Security

All credentials are encrypted:
  • AES-256-GCM encryption at rest
  • TLS transmission
  • Automatic token rotation (when available)
  • No secrets in logs
Isolation:
  • Per-gateway credentials
  • Connectors can’t access each other’s tokens
  • Audit trail of all connector calls
Rate limiting:
  • Per-connector limits
  • Per-operation limits
  • Backoff on 429 responses

​
Connector as MCP Tools

Once attached, connectors appear as tools: 
// List available tools
const tools = await gateway.listTools();

// Returns
[
  {
    name: "shopify_list_orders",
    description: "Get all orders"
  },
  {
    name: "shopify_create_order",
    description: "Create a new order"
  },
  // ... more tools
]
Tool execution: 
const result = await gateway.callTool("shopify_list_orders", {});

// Returns API response
{
  "orders": [
    {
      "id": 12345,
      "email": "customer@example.com",
      "total_price": "99.99"
    }
  ]
}

​
Best Practices

Test Before Deploying

Test connector with real API calls before attaching to production agents.

Least Privilege

Create API keys with minimal scopes. Don’t use full admin tokens.

Monitor Usage

Check API call counts and error rates. Watch for rate limiting.

Rotate Secrets

Change API keys quarterly. Revoke old keys immediately after.

​
Common Patterns

​
Pattern: CRM Integration

Connector: Salesforce
├─ Operations:
│  ├─ get_account (by ID)
│  ├─ list_leads
│  ├─ create_opportunity
│  └─ update_contact
└─ Auth: OAuth 2.1

Agent: CRM Assistant
├─ Capabilities: Salesforce Connector
├─ Instructions: "Access CRM data. Create/update opportunities when authorized."

​
Pattern: Multi-API Data Aggregation

Connector 1: Stripe
├─ list_charges
├─ refund_charge

Connector 2: Square
├─ list_transactions

Connector 3: PayPal
├─ get_transaction

Agent: Finance Dashboard
├─ Capabilities: All three connectors
├─ Task: "Aggregate transactions from all payment providers"

​
Pattern: Internal Service Integration

Connector: Custom MCP (your internal server)
├─ Transport: https://internal-api.example.com/mcp
├─ Auth: API key

Agent: Operations Bot
├─ Capabilities: Internal connector
├─ Task: "Check order status, manage inventory"

​
Troubleshooting

ProblemSolution
401 UnauthorizedVerify auth token is valid and has required scopes
403 ForbiddenCheck if token has permission for the operation
429 Rate LimitedReduce call frequency. Request higher limits from service.
TimeoutOperation takes too long. Try splitting into smaller requests.
Invalid responseService API changed. Update operation definitions.

​
Connector Limits

  • API timeout: 60 seconds per call
  • Response size: 10 MB
  • Operations per connector: 100
  • Concurrent calls: 10 per gateway
Contact support to increase limits for enterprise use.
Next: Explore Memory System that powers agent context.