> For the complete documentation index, see [llms.txt](https://notara-1.gitbook.io/notara-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://notara-1.gitbook.io/notara-docs/connectors/custom-http.md).

# Custom HTTP

The Custom HTTP connector lets you expose any REST API as a set of agent tools. Define endpoint paths, HTTP methods, and JSON Schema for inputs and outputs — the agent can then call your internal APIs, third-party services, or any REST endpoint as part of a conversation.

## When to Use This

Use the Custom HTTP connector when:

* You have an internal API the agent should be able to query or trigger
* You want to connect a service Notara doesn't have a built-in connector for
* You're building a proof-of-concept before writing a full MCP server

For more complex integrations with their own authentication flows, consider the [Remote MCP connector](#remote-mcp-vs-custom-http) instead.

## Setup

1. In the Notara dashboard, go to **Tools → Custom HTTP**.
2. Click **New Custom Connector**.
3. Fill in the base configuration:

| Field               | Description                                                              |
| ------------------- | ------------------------------------------------------------------------ |
| **Name**            | Human-readable name for this connector (e.g., "Internal API")            |
| **Base URL**        | The root URL of the API (e.g., `https://api.internal.acme.com`)          |
| **Default Headers** | Headers sent with every request (e.g., `Content-Type: application/json`) |
| **Auth Type**       | None, Bearer Token, API Key header, or Basic Auth                        |
| **Auth Value**      | Your API key or token                                                    |

4. Add tool definitions (see below).
5. Click **Save & Test** to verify the connector can reach the endpoint.

## Defining Tools

Each endpoint you want the agent to call becomes a **tool**. Click **Add Tool** to define one:

```json
{
  "name": "get_customer_health",
  "description": "Look up health score and risk flag for a customer by ID",
  "method": "GET",
  "path": "/customers/{customerId}/health",
  "capability": "read",
  "inputSchema": {
    "type": "object",
    "properties": {
      "customerId": {
        "type": "string",
        "description": "The customer's UUID"
      }
    },
    "required": ["customerId"]
  }
}
```

For POST endpoints:

```json
{
  "name": "trigger_onboarding_email",
  "description": "Trigger the onboarding email sequence for a new user",
  "method": "POST",
  "path": "/emails/onboarding",
  "capability": "write",
  "inputSchema": {
    "type": "object",
    "properties": {
      "userId": { "type": "string" },
      "planType": { "type": "string", "enum": ["pro", "enterprise"] }
    },
    "required": ["userId", "planType"]
  }
}
```

## Capability Levels

Set `capability` to `read`, `write`, or `destructive` for each tool. This determines the default permission level:

* `read` — executes immediately
* `write` — requires admin approval
* `destructive` — admin only + in-channel confirm prompt

Use `destructive` for tools that delete data, send external notifications to many users, or make large irreversible changes.

## JSON Schema Passthrough

The `inputSchema` you define is passed through to the LLM without modification. This means you can use any valid JSON Schema, including `enum`, `anyOf`, nested objects, and `$ref` references. The agent uses the schema to construct valid requests.

The response from your API is also passed back to the agent as-is. Structure your API responses to be readable — include human-friendly field names and avoid deeply nested structures when a flat one works.

## Security Considerations

### SSRF Protection

Notara validates all base URLs at save time against an allowlist. Private IP ranges (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `127.0.0.1`, `::1`) are blocked to prevent server-side request forgery attacks. Ensure your internal APIs are accessible via a public hostname or a static IP not in the private range.

### DNS Rebinding

At v1, Notara performs a URL safety check at save time and at connection time. A determined attacker who can control DNS could potentially redirect a previously safe hostname after connection. This is a known limitation for v1. If your API is sensitive, use a static IP or add your own verification at the API layer.

### Credential Security

Auth credentials (API keys, tokens) for custom HTTP connectors are encrypted at rest with AES-256-GCM, the same as all other connector credentials in Notara.

## Remote MCP vs Custom HTTP

|                  | Custom HTTP            | Remote MCP                      |
| ---------------- | ---------------------- | ------------------------------- |
| Protocol         | Plain REST             | MCP over SSE                    |
| Tool definition  | Manual JSON Schema     | Auto-discovered from MCP server |
| Auth             | API key, Bearer, Basic | Bearer token                    |
| Best for         | Simple REST endpoints  | Full-featured MCP servers       |
| Setup complexity | Low                    | Medium                          |

If the service you want to connect publishes its own MCP server (many modern dev tools do), use the Remote MCP connector type instead — it auto-discovers tools rather than requiring manual definition.