Any REST or SOAP system, without code
How to connect a system SourceLace has no ready-made connector for, when it has a REST API (with or without an OpenAPI document) or a SOAP web service (with a WSDL). An admin describes the API on Connections; nobody writes or runs any code. For systems with no web API at all, build your own connector instead.
Status: Pilot. New or partial, offered to pilot customers. Neither kind has been used with a customer's live system yet.
At a glance
| Connects through | Sign-in | Network | Status | First test question | |
|---|---|---|---|---|---|
| Any REST API | The API's own REST endpoints, from its OpenAPI document or endpoints an admin lists | Personal sign-in with oauth; shared account otherwise |
Allow SourceLace's IP addresses, if the API limits them | Pilot | Test connection on Connections, then "Which operations does rest:billing offer?" |
| Any SOAP web service | The service's SOAP 1.1 or 1.2 endpoint, from its WSDL | Personal sign-in with oauth; shared account otherwise |
Allow SourceLace's IP addresses, if the service limits them | Pilot | Test connection, then "Which operations does soap:customers offer?" |
Add each source with the usual steps. The network answers are explained in What your network needs. If the first test question fails, the error message tells you what to fix: look it up under When something goes wrong below.
How it works
- REST (
rest): every operation in the API's description becomes an object. People (and their AI) find operations with search, see each one's parameters, and read with a query that names an operation and its parameters, in therest_jsonlanguage:{"operation": "listInvoices", "params": {"status": "open"}}. SourceLace checks every query against the description (the operation exists and is a read, required parameters are there, nothing unknown, values have the right type and allowed values) before anything is sent, and pages through the results itself. - SOAP (
soap): every operation the admin marks as a read becomes an object, queried the same way in thesoap_jsonlanguage:{"operation": "GetCustomers", "params": {"Country": "DE"}}. SourceLace builds the SOAP 1.1 or 1.2 message, reads the answer, and turns SOAP faults into messages that say what to fix. - Only reads, unless you allow more. For REST, only GET operations are reads. Every other operation (POST, PUT, PATCH, DELETE) is off until an admin switches it on by name. A switched-on operation never runs as a query: it runs only as a change, which the person sees first (the exact request, and the record's current values when the API has a GET on the same path) and confirms. SOAP sources are read-only.
- Answers are data. What the system sends back only ever becomes rows; nothing in it is followed as an instruction.
How people sign in
Choice (auth) |
Who the system sees | When to use it |
|---|---|---|
oauth |
Each person, with their own account (OAuth 2.0 authorization code flow with PKCE) | Recommended whenever the system offers OAuth: its own permissions then apply to each person. |
api_key, bearer, basic |
One shared account for everyone who uses the source | Only when the system offers nothing per person. |
none |
Nobody (a public API) | Public data only. |
Shared access: with api_key, bearer, basic or none, everyone who may use the source acts as the same account, so the system cannot tell people apart and cannot apply its own permissions per person. SourceLace says so wherever the source is listed. Give such a key the least access it needs (read-only if possible), and limit who can use the source with access by group.
Secrets (the OAuth client secret, the API key, token or password) are stored encrypted with your organization's key, shown only as "(saved)", never sent anywhere but the system itself, and never written to logs or answers.
Add a REST source (SourceLace admin)
- If the system offers OAuth, have its admin register an OAuth app (client) for SourceLace, with exactly this redirect URL,
https://mcp.sourcelace.ai/connect/callback, and only the read scopes people need. Otherwise, create an API key or a service account with the least access needed. - On Connections → Add a source, choose Any REST API, no code (
rest), give it a name (such asrest:billing) and a label. - Paste or load the API's OpenAPI 3 or Swagger 2 document (JSON or YAML), or give its address in
spec_url: SourceLace fetches it once when you save and keeps it. To refresh it later, empty the document box and save again. Without an OpenAPI document, list a few endpoints by hand (below). - Choose how people sign in, and fill in its options.
- Save, then press Test connection: SourceLace checks the description, that the address may be called, and (for shared access) reads a few records.
- To allow changes, turn on Allow changes and name the operations, such as
createInvoice, updateInvoice.
| Option | Example | What it is |
|---|---|---|
spec |
(an OpenAPI document) | The API's description, JSON or YAML. Up to 3 MB. Other files it refers to are not fetched. |
spec_url |
https://api.corvanta.com/openapi.json |
Where to fetch spec once, when spec is empty. |
endpoints |
(JSON, below) | Endpoints written by hand; they add to (or replace, by name) the document's operations. |
base_url |
https://api.corvanta.com/v1 |
The API's address, when the document has none, or to use another (such as a sandbox). Needed when the document's address has a part each customer fills in, such as https://{subdomain}.zendesk.com/api/v2. |
auth |
oauth |
oauth, api_key, bearer, basic or none. |
client_id, client_secret |
The OAuth client (the secret only for a confidential client). | |
authorize_url, token_url, scopes |
https://auth.corvanta.com/oauth/authorize |
OAuth addresses and scopes. Empty: taken from the OpenAPI document's OAuth flow. |
secret |
The API key, token or password for shared access. | |
key_name, key_in |
X-API-Key, header |
For api_key: the header or query parameter that carries it. Empty: where the OpenAPI document says its API key goes, otherwise the header X-API-Key. |
username |
svc-sourcelace |
For basic. |
test_operation |
listInvoices |
The read Test connection uses (default: the first GET without required parameters). |
Endpoints by hand look like this (only name and path are required; method defaults to GET):
{"base_url": "https://api.corvanta.com/v1",
"endpoints": [
{"name": "invoices", "method": "GET", "path": "/invoices", "description": "Invoices, newest first",
"params": [{"name": "status", "in": "query", "enum": ["open", "paid"]}],
"rows": "data",
"paging": {"style": "cursor", "param": "starting_after", "next": "meta.next_cursor"}},
{"name": "invoice", "path": "/invoices/{id}"},
{"name": "createInvoice", "method": "POST", "path": "/invoices", "body": ["amount", "customer"]}]}
params: each withname,in(query,pathorheader), and optionallyrequired,type(string,integer,number,boolean,array),enumanddescription. Every{name}in the path is a required path parameter.rows: where the records are in the answer, as a dotted path (data,result.items); empty for an answer that is itself the list. Left out, SourceLace looks for a list such asdata,itemsorresults.paging:styleispage(withparam, such aspage),offset(withparam, such asoffset, andsize_param),cursor(withparamandnext, the dotted path to the next cursor in the answer),link(theLink: <…>; rel="next"header) ornone.size_paramandsizeset how many rows a page asks for. For OpenAPI documents SourceLace works this out from the parameter names; an operation can also say it withx-sourcelace-pagingandx-sourcelace-rows.body: for changes, the JSON body's field names.
Changes
A change names its operation as the object: POST operations are creates, PUT and PATCH updates, DELETE deletes. Its fields are the operation's parameters (by name) and its JSON body fields; the record id fills the path's last parameter (or several, as a JSON object such as {"customerId": "C-1", "id": "7"}). Each change shows the exact request before the person confirms it.
Add a SOAP source (SourceLace admin)
- Create a service account with read-only access, or an OAuth client if the service supports it.
- On Connections → Add a source, choose Any SOAP web service, no code (
soap), with a name such assoap:customers. - Paste or load the WSDL, or give its address in
wsdl_url: SourceLace fetches it once when you save and keeps it (empty the box and save again to refresh it). - List the operations that only read in
read_operations, such asGetCustomers, GetOrders. Nothing else can run. - Choose how people sign in (the same choices and options as REST), save, and press Test connection.
| Option | Example | What it is |
|---|---|---|
wsdl |
(a WSDL document) | The service's WSDL 1.1. Up to 3 MB. Imported files are not fetched: their types show as unknown, and parameters are passed by name. |
wsdl_url |
https://soap.corvanta.com/customers?wsdl |
Where to fetch wsdl once, when it is empty. |
read_operations |
GetCustomers, GetOrders |
The only operations that may run. |
endpoint |
https://soap.corvanta.com/customers |
The service's address, if not the WSDL's. Needed when the WSDL names an address inside the owner's network, as exported WSDLs often do. |
soap_version |
1.2 |
SOAP 1.1 or 1.2; empty uses the WSDL's (1.1 first). |
Supported: document/literal (including the common "wrapped" style) and rpc/literal. SOAP encoding (use="encoded") is not.
Filters you declare
What it is. When someone asks a question that combines this system with others, SourceLace reads the system's list and then narrows it down itself. On a long list that is slow, because every record travels first. A filter tells SourceLace that a field can be narrowed by one of the system's own parameters, so it asks the system for only the records it needs. Filters are optional: without them everything works, only slower on long lists. They work the same for a REST API, a SOAP service and a source from a vendor's own tools (see Outside MCP servers).
Who does it, and where. A SourceLace admin, on Connections: choose Edit on the source, then find Filters the source can apply. Save the source first (a new source has no filters box until it is saved), and connect it with your own sign-in under My connections if it uses each person's own sign-in: the test reads as you.
Three words, used the same way everywhere:
- a field is a column of the records, such as
statusordue_date; - a filter is one line of the form: this field is narrowed by this parameter, with this meaning;
- a record is one item the system returns, such as one invoice.
An example in two minutes (REST)
Acme Billing's list of invoices (the operation listInvoices) takes two parameters, status and due_before.
- Choose Edit on the source and open Show an example if you want it beside you.
- Choose Add a filter. Operation
listInvoices, fieldstatus, filtered by parameterstatus, the field is equal to. - Choose Add a filter again. Operation
listInvoices, fielddue_date, filtered by parameterdue_before, the field is before (not including). If Acme's documentation saysdue_beforeincludes the day itself, choose is on or before instead. - Choose Save, then press Test next to each filter. Each says Passed: used, Failed: not used or Could not be tested: not used, and a line under it says why in counts.
- Ask: "Which open invoices are due before 30 November?" together with another system.
What SourceLace sends: GET /invoices?status=open&due_before=2026-11-30. About 240 invoices come back instead of all 40,000. SourceLace still removes any record that does not match and applies the rest of your question (such as the customer) itself. The answer's source details show the exact request, so you can always see what was asked.
Check that it worked: open the answer's source details and look for your parameter in the request. If it is not there, the filter was not used: look at its status in the form.
What each meaning is for
Choose the meaning that matches what the system's parameter does, as its documentation says. When unsure, choose the wider one: SourceLace removes any extra records, and the test tells you if the system loses any.
| Meaning | The system's parameter returns records whose field… | Used for questions that say |
|---|---|---|
| is equal to | equals the value | is equal to |
| is before (not including) | is earlier than the value, not the value itself | before |
| is on or before | is earlier than the value, or the value itself | before, or on or before |
| is after (not including) | is later than the value, not the value itself | after |
| is on or after | is later than the value, or the value itself | after, or on or after |
A filter is never used in a way that could return fewer records than the question needs: "is before (not including)" is never used for "on or before", because that would drop the records on the day itself.
The test
Press Test next to a filter to check it before it is used. SourceLace reads the first page of the list twice as you, once without the filter and once with it. It picks a value that occurs in the data (the most common status, or a middle date), works out which records should match, and checks that every one of them came back with the filter.
- Passed: used. The filter lost no record on that page. Extra records are fine: SourceLace removes them. From now on, questions send this filter.
- Failed: not used. Some records that should match were missing, so the filter loses records. Check the parameter and the meaning (often "before" against "on or before"), save, and test again. The source is read in full instead, so answers stay correct.
- Could not be tested: not used. The line says why: the first page has too few records or the same value in every record, the field is not a number or a date (for "before" and "after"), the value cannot be sent as the parameter's type, or the system did not answer. Nothing is wrong yet; the filter is simply not used.
A filter is used only after it passes. If you change a filter in any way, it must be tested again. The test reads at most 100 records on each side, counts against the source's requests per minute like any question, and shows you counts and plain words only: it does not show or keep the records. SourceLace keeps your filters and whether each passed, with the source, until you remove them.
The test looks at one page, so it cannot prove a filter is right for every record. It catches the usual mistakes: the wrong field, the wrong direction, or a parameter that means something else.
More examples
SOAP. A customer service's operation GetOrders takes a plain parameter Status. Add one filter: operation GetOrders, field Status, filtered by Status, is equal to. A question about shipped orders then calls GetOrders with Status set to Shipped. Only plain, top-level parameters can carry a filter, not nested or repeated ones.
A range. The same list has created_after and created_before. Add created filtered by created_after is on or after, and created filtered by created_before is on or before. A question about the first quarter sends both.
A vendor's own tool works the same way: see Filters for a tool.
The same list as JSON (advanced)
Under the form, Edit as JSON (advanced) shows the same filters as a list you can paste or edit; the form and the JSON are one list, checked the same way. Each entry has operation (the operation or tool), field, sent_as (the parameter or argument) and meaning (equals, before, on_or_before, after or on_or_after):
[
{"operation": "listInvoices", "field": "status", "sent_as": "status", "meaning": "equals"},
{"operation": "listInvoices", "field": "due_date", "sent_as": "due_before", "meaning": "before"}
]
What is sent, and what is not
- Only plain comparisons on a field you declared: is equal to, before, after, and a range made of two of them. Questions with "or", "in a list", "contains", "is empty" or "is not" stay with SourceLace, which filters the records itself.
- Dates go as
YYYY-MM-DD, whole numbers and numbers as numbers, true and false astrueandfalse, and text as it is. A date with a time of day is not sent, and neither is a number that would change on the way. Those are filtered by SourceLace. - Filters never change what you are allowed to see: your own sign-in and your organization's rules apply to every record, as before.
- Only reads. A filter on a change operation is refused.
- A read that needs a value to run, such as an invoice by its id, cannot be read as a table in a question across systems unless a tested filter supplies that value. Use a separate question for it.
- A filter on a parameter that SourceLace manages itself (the page number, the page size) is refused.
What the system's admin does
About 15 minutes, once you have the API's documentation.
Who: an admin of the system you connect, with the right to register API clients or create API keys there (often called Administrator, Developer or Integration admin). For SOAP, the service's owner.
For a REST API
-
Find the API description. In the vendor's developer documentation, look for an OpenAPI or Swagger file (a JSON or YAML file, often named after OpenAPI or Swagger). Download it, or copy its address for
spec_url. Without one, list the endpoints by hand (above). -
Find your own API address. Many vendors give each customer an address such as
https://corvanta.zendesk.com/api/v2. If the description's address has a part to fill in, such as{subdomain}, enter your own address as Base address (base_url). -
For each person's own sign-in (
oauth, recommended): in the system's admin or developer settings, register an OAuth app (also called a client or an API client) for SourceLace:- grant type Authorization code (with PKCE if offered);
- redirect URL exactly
https://mcp.sourcelace.ai/connect/callback; - only the read scopes people need (add write scopes only for operations you switch on as changes).
Copy the client ID, and the client secret if the app is confidential (a public client has none: leave the secret empty in SourceLace). If the description has no OAuth section, also copy the authorization address and token address from the vendor's documentation.
-
For a shared key (
api_key,bearerorbasic): create a service account with read-only access, and a key or token for it. Note where the API's documentation says the key goes (a header such asX-API-Key, or a query parameter such asapi_key). SourceLace uses what the OpenAPI document says when you leave Send the key as empty. -
Let SourceLace in. If the API accepts only some IP addresses, allow SourceLace's (ask support for the list).
For a SOAP service
- Get the WSDL. The service's owner can send it, or it is often at the service's address followed by
?wsdl. - Give the public address. The WSDL names the address it was exported from, often the developer's own computer or a host inside your network. If so, enter the service's public
https://address as Service address (endpoint). - Choose the sign-in. SourceLace sends HTTP Basic (a service account's user name and password), a bearer token, an API key, or each person's OAuth sign-in. It does not put a WS-Security user name token inside the SOAP message: if the service wants that, ask its owner to also accept Basic or a token for SourceLace.
- Let SourceLace in, as for REST.
Check that it worked: save the source and press Test connection. It reads the description and, for a shared account, a few records. With oauth, click Connect and ask for a few records.
If it did not work: look up the message in When something goes wrong. The OpenAPI standard is described at OpenAPI Initiative, and WSDL at W3C Web Services Description Language.
Safety
These sources reach addresses your admin types in, so SourceLace guards every request:
- only
https://; - in SourceLace's cloud, only addresses on the public internet: private, loopback, link-local and other reserved addresses are refused, every address a name resolves to is checked, and the request goes to the address that was checked. Cloud metadata addresses are always refused, on any server;
- redirects are never followed, and next-page links must stay on the API's own address;
- answers are limited to 10 MB, and each query to the organization's query time (
queries.timeout_seconds) and row cap; - each source sends at most
queries.api_requests_per_minuterequests a minute (120 by default; see Limits); - nothing of SourceLace's own (cookies, tokens, keys) is ever sent: only the source's own credential;
- XML (the WSDL and every SOAP answer) is read with DTDs and entities refused, so XML attacks such as external entities and "billion laughs" do not work.
When something goes wrong
| What you see | What to do |
|---|---|
| "Give the source an API description: paste or upload an OpenAPI document (option spec), or list a few endpoints by hand (option endpoints)." | Add the OpenAPI document, spec_url, or endpoints. |
| "Give the source its WSDL: paste or upload it (option wsdl), or set wsdl_url." | Add the WSDL, or wsdl_url. |
| "Fetching the API description from spec_url answered HTTP ..." (or "Fetching the WSDL from wsdl_url ...") | Check the address, or paste the document instead. |
| "... is neither valid JSON nor valid YAML ..." or "This is not a WSDL 1.1 document ..." | Use an OpenAPI 3 or Swagger 2 document, or a WSDL 1.1. |
| "Set the option read_operations: the operations that only read data ..." | List the SOAP operations that only read, separated by commas. |
| "Set the option auth: oauth (each person signs in with their own account, recommended), api_key, bearer or basic ..., or none." | Choose how people sign in. |
| "With auth ..., set the option secret ..." or "With auth basic, set the option username ..." | Fill in the shared key, token or password (and the user name for basic). |
| "With auth oauth, set the options authorize_url and token_url ..." | Copy both addresses from the system's OAuth documentation, or use an OpenAPI document that lists them. |
| "... must start with https://. ..." | Use the https:// address. |
| "... names a cloud metadata or internal host, which SourceLace never calls." | Use the API's public address. |
| "...: ... leads to a private or reserved network address, so SourceLace did not call it." | SourceLace's cloud only calls addresses on the internet. Use a public address. |
| "The address of ... could not be found. Check its spelling." | Fix the host name in base_url, endpoint, or the document. |
| "... sign-in to ... failed (...). Connect the source again." | The system's own reason is in brackets. Check that the OAuth client's redirect URL is exactly https://mcp.sourcelace.ai/connect/callback, and the client ID and secret. |
| "... sign-in to ... failed (invalid_client ...). The system does not accept SourceLace's OAuth client ..." | Copy the client ID and secret again from the app registered in the system. A public client has no secret: leave it empty. |
| "... sign-in to ... failed (unauthorized_client ...). The OAuth client may not use the authorization code sign-in ..." | In the system, turn on the Authorization code grant type for the client. |
| "... sign-in to ... failed (invalid_grant ...). The client's registered redirect URL must be exactly ..." | Correct the redirect URL registered for the client, then connect again. |
| "The API description's address (...) has parts each customer fills in (...). Set Base address (base_url) to your own, ..." | Enter your own API address as Base address. |
| "... refused the source's saved credential (HTTP 401). ... This source sends the key as the ..." | Check the key, and that Send the key as and Send the key in match the API's documentation. |
| "The WSDL gives the service's address as ..., which SourceLace cannot call from the internet. ..." | Enter the service's public https:// address as Service address. |
| "... wants WS-Security sign-in inside the SOAP message, which SourceLace does not send. ..." | Ask the service's owner whether it also accepts HTTP Basic or a bearer token, and choose that under How people sign in. |
| "... has no operation .... Use search_schema to list them." | Use an operation name that search_schema shows. |
| "... is a POST, which changes data, so query cannot run it. ..." | Changes go through propose_change, and only for operations an admin switched on. |
| "... is not switched on as a change for .... An admin can switch it on." | A SourceLace admin turns on Allow changes and names the operation. |
| "... needs .... Use describe_object to see its parameters." or "... has no parameter ...." | Fix the query's parameters. |
| "... has had ... requests in the last minute, the most SourceLace sends it. ..." | Wait the time shown, or ask for more rows per request. |
| "... did not answer within ... seconds. ..." or "... sent an answer larger than 10 MB. ..." | Ask for fewer rows or fields. |
| "... answered with ... instead of JSON, so SourceLace could not read it. ..." | Check base_url and that the operation returns JSON. |
| "... uses SOAP encoding (use=encoded), which SourceLace does not support." | That operation cannot be used. |
| "SOAP sources are read-only for now: turn changes off for this source." | Turn Allow changes off. |
| "The filters are not valid JSON. Write a list such as [...], or use the form." or "The filters must be a list, one entry per field." | Fix the JSON, or clear the box and use the form. |
| "At most 200 filters can be declared." | Remove filters you do not need. |
| "Filter 1: meaning: ..." or "Filter 1: field: ..." | That entry is missing a part or has a meaning that is not one of equals, before, on_or_before, after, on_or_after. |
| "Filter 2: listInvoices already filters status with the meaning equals." | Two filters say the same thing. Remove one. |
| "The filters need fixing. listInvoices has no query parameter ... that can carry a filter. Its query parameters: ..." | Choose one of the parameters it lists. The page number and page size are SourceLace's own and cannot be used. |
| "The filters need fixing. ... has no field .... Its fields: ..." | Choose one of the fields it lists. |
| "The filters need fixing. ... is not a read operation of ...." | Only reads can take filters. Choose a read operation. |
| "Save the filter first, then test it." | Save the source, then press Test. |
| "Connect this source with your own sign-in first (My connections), then test the filter: the test reads as you." | Connect the source under My connections, then test again. |
| "Failed. 3 of the 12 records that should match were missing when the filter was sent, so the filter loses records and is not used. ..." | Check the parameter and the meaning, save, and test again. |
| "... could not be tested: ... The filter is not used until it passes." | The reason follows the colon. Add or load data so the first page has different values, or choose another field. |
| "... needs ..., so it cannot be read as a table in a question across systems unless a filter is declared for it. ..." | That read needs a value. Ask about it in a separate question, or declare and test a filter that supplies the value. |
| "... does not allow this (HTTP 403)." | The system refused. The rest of the message says whether it was your own account or the shared credential that lacks the permission. |
| "... found nothing at that address (HTTP 404). Check the parameters." | A parameter (such as an id) points at something that does not exist. |
| "... answered with a redirect (HTTP ...), which SourceLace never follows." | The API moved to another address. |
| "... took longer than the query time limit. Ask for fewer rows." or "... failed (HTTP ...). Try again later; if it keeps failing, tell your admin." | The system was slow or had a problem. |
| "REST sources have no related lists. Query the related operation instead." or "SOAP sources have no get_record: query the operation that reads one record instead." | These sources have no related lists or record-by-id calls. |
| "... answered with a web page instead of data (HTTP ...)." or "... sent back data in an unexpected shape." | The system sent a page (often a sign-in or error page) instead of data. |
| "... needs the option '...', such as ...." or "... needs the option 'client_id': ..." | An OAuth setting is missing. |
| "... failed (a SOAP server fault)." | The SOAP service reported a fault of its own. |
| "... uses a DTD or XML entities, which SourceLace refuses for safety" or "... is not well-formed XML (...)." or "... sent an answer SourceLace could not read." | The WSDL or the service's answer is not safe or valid XML. |